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

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 will be the same no matter which endpoint returns it (so trayNumber is the tray number an order is in whether you use GET /orders/123456 or GET /orders/123456/status

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.