Conventions

Unless otherwise noted, endpoints for the Version 2 API will conform to the following conventions.

URLs

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.

{
  "code": "001",
  "desc": "WAITING FOR LENSES",
  "customerDesc": "0001",
  "operator": false
}

If the endpoint returns a list of objects, it will be an object with the following structure where models is the list of resources and count is the total number of resources available (the amount that would be returned if limit and offset are not provided)

{
  "models": [
    {
      "code": "001",
      "desc": "WAITING FOR LENSES",
      "customerDesc": "0001",
      "operator": false
    },
    {
      "code": "002",
      "desc": "FRAME RECEIVED",
      "customerDesc": "FRAME RECEIVED",
      "operator": false
    }
  ],
  "count": 144
}

Errors

In the event a request cannot be completed, the response body will be structured like:

{
    "error": "A description of what went wrong",
    "details": ["An array that may contain additional information"]
}

For example, trying to create a new order with POST /api/v2/orders may fail for multiple reasons. In this case the error field will tell you that the order was not created, and the details field will include every reason why.


  "error": "Incorrect arguments provided",
  "details": [
    "jobType does not have a valid value",
    "frameA must be greater than 30",
    "frameB must be greater than 15",
    "frameED must be greater than 30"
  ]
}

An error will set one of the following HTTP status codes

400: One or more parameters sent in the request had an invalid value
401: Authentication is required and no valid token was supplied
402: The installation of the API is not correctly licensed for the requested operation
404: the requested resource does not exist
500: Any other issue

Naming Conventions

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 across different endpoints (so trayNumber is the tray number of an order 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.