Page Comparison

...

• All version 2 endpoints are mounted under the /api/v2/* route (e.g. GET /api/v2/addons)

• Any endpoint that operates on a particular resource will use the resource’s identifying code in the route (e.g. to work with the order 123456 you will use URLs like GET /api/v2/orders/123456)

• Resources will support one or more of the following routes:

  • GET /api/v2/resource: list all available resources

    • Example: GET /api/v2/addons returns the list of addons set up in Rx-Universe

    • These support the property limit, which will only return a subset of records (so limit=10 returns a maximum of 10 addons) and offset, which skips the first several records (limit=10&offset-=0 returns the first page of 10 records; limit=10&offset=10 returns the second page of 10 records, etc.)

  • GET /api/v2/resource/:id: returns a single resource

    • Example: GET /api/v2/addons/SRC returns only information about the addon with code SRC

    • The model returned will have the same structure as the one returned in the list; in some endpoints it may have extra details.

  • GET /api/v2/resource/:id/extra_info: returns particular information about a resource

    • Example: GET /api/v2/orders/123456/pick returns the lens pick verification information for order 123456

  • POST /api/v2/resource: creates a new resource

    • Example: POST /api/v2/orders will create a new order with the submitted information

    • This will return a model representing the new resource or an error

  • POST /api/v2/resource/:id/action: performs an action on the requested resource

    • Example: POST /api/v2/orders/123456/pick: performs lens pick verification on order 123456 with the provided information

    • This will return a message indication success or an error

  • DELETE /api/v2/resource/:id: requests the deletion of a resource

    • Example: DELETE /api/v2/orders/123456: requests the cancellation of order 123456

    • This will return a model representing the last known state of the resource or an error message. This may be a subset of the fields returned by the GET action.

• Note: in some cases a POST may be used for a query that does not update the system state if the parameters would tend to exceed the maximum standard URL length of 2048 characters in a GET

Successful Responses

All endpoints return a JSON object at the top level. If the endpoint operates on a single resource, this will be the resource itself.

...

• Properties are named in camelCase

• Any property that is for the right eye will have the prefix rt

• Any property that is for the left eye will have the prefix lt

• Any occurrence of a property for a particular resource will be the same no matter which endpoint returns it across different endpoints (so trayNumber is the tray number of an order is in whether you use GET /orders/123456 or GET /orders/123456/status or POST /orders

Validations

• All incoming string parameters have a maximum length that will be documented in their description

• All incoming number parameters have a maximum and minimum value that will be documented in their description

• All incoming array parameters have a maximum length that will be documented in their description

• If a parameter is not flagged as required it can be omitted to use default behavior particular to that field - for example, not specifying trayNumber when creating a new order will result in one being automatically generated.