Route Structure #

Each endpoint is meant to represent a collection of the given object and are always pluralized. Spaces are replaced with underscores.

List #

To get a list of all records:

GET /maintenance/work_orders

Read #

To retrieve a specific record, append the ID as a subsequent path segment:

GET /maintenance/work_orders/12345

The payload returned by each endpoint will only contain information that is contained directly within the record itself. In the case of work orders, things like status, priority and department would be returned. Notes attached to a work order are available as a child collection.

Create #

To create a new instance of an object, POST to the same endpoint that is used to list records:

POST /maintenance/work_orders
Content-Type: application/json
 
{
    "department_id": 1,
    "work_order_type_id": 2,
    "work_order_type_group_id": 3
}

The body of the request is a JSON representation of the object. Payloads are documented using OpenAPI, for which a link is available in the right column.

Update #

Updating a specific record can be done using PATCH or PUT against the record’s endpoint:

PATCH /maintenance/work_orders/12345
 
{
    "priority": 3
}

PATCH will update the record in place, while PUT will override the document. PATCH is capable of performing partial updates, as shown above. The priority of work order 12345 will be changed to 3 and all other fields will be left unchanged. If the same request were to be sent as a PUT instead, all fields not specified in the payload would be reset to their default values.

Delete #

DELETE is also directed at the record’s endpoint:

DELETE /maintenance/work_orders/12345

All deletions are soft. The API does not provide a way to perform a hard delete.

Children #

Child collections are accessed by adding another path segment:

GET /maintenance/work_orders/12345/notes

The above would return all notes attached to work order 12345. Children only go one level deep; going any deeper is redundant due to the IDs in the URL. Getting all service requests attached to a work order A, attached to a service request B (/maintenance/service_requests/B/work_orders/A/service_requests) would just return B.