Endpoints

Within each resource, several types of endpoints are provided to accomplish different tasks concering that resource.

/resources (index)

Index endpoints will return a collection of the given type of resource, optionally filtered and sorted by parameters you provide.

The response to an index endpoint always contains a key with the plural name of the endpoint and a corresponding array of resource objects matching the query provided.

{
  "resources": [
    // the actual resources are contained in this array. The endpoint producing this response would be /resources
    {
      // fields appear here
    } // one object is in the array for each resource
  ]
}

Each resource object is identical to what would be returned on the equivalent show endpoint.

A 200 OK response code is returned on a successful index request.

GET /resources/:id (show)

Show endpoints return a single resource, and may accept additional parameters to alter the presentation of fields within the resource.

The response to a show endpoint always contains a key with the singular name of the endpoint/resource and a corresponding object containing the resource's fields:

{
  "resource": { // the endpoint producing this response would be /resources/:id
    … // fields appear here
  }
}

The actual key name varies based on the endpoint. Consult the reference documentation for specifics.

A 200 OK response code is returned on a successful show request.

POST /resources (create)

Create endpoints will create a new resource according to the payload specified. They accept a body with the same format as in a show response, and will return a response reflecting what the created resource looks like. If properly specified, this will mirror the request body, but is likely to contain additional readonly fields generated by the server.

If readOnly fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored.

A 201 Created response code is returned on a successful create request.

A 4xx response code is sent if something in the request was invalid, such as omitting parameters required to create the resource.

PUT /resources/:id (update single)

Update single endpoints will modify the state of an existing resource, identified by the id and type fields within the request body. The body has the same format as would be returned from the equivalent show endpoint. Not all required fields for the resource must be specified; only those whose state is to be changed must be included.

If readonly fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored.

A 200 OK response code is returned on a successful update single request.

A 4xx response code is sent if something in the request was invalid, such as providing an invalid value for a field within the resource.

PUT /resources (update multiple)

Update multiple endpoints will modify the state of several resources at once, each identified by the id and type fields within the resource's body in the resource array. The request body mirrors the same format as would be returned from the equivalent index endpoint.

Each resource specified in the array follows the same rules as would be followed in the equivalent update single endpoint. If any resource in the request is invalid, the entire request will be invalid and no resources will be updated.

A 200 OK response code is sent to a successful update multiple request.

A 4xx response code is returned if something in the request was invalid, such as providing an invalid value for a field within a given resource.

DELETE /resources/:id (delete)

Delete endpoints will cause the specified resource to be removed from the account. Subsequent requests to the associated index endpoint will not display the resource in the response, and subsequent requests to the associated show endpoint will return a 404 response code.

However, the id of the resource deleted, in combination with its type, still serve to uniquely identify the deleted resource. No resources of the same type will have the same id in the future.

In addition, deleted resources may still be referenced by other resources. In these cases, the deleted resource will always be shown as a resource reference.

A 204 No content response code is returned to a successful delete request.

A 4xx response code is sent if it was not possible to delete the resource. The response body will contain more specific errors about why the delete request failed.

POST /resources/:id/{verb} (verb)

Verb endpoints exist where an action needs to be carried out on a resource that goes beyond updating its immediate state. These endpoints will take a set of parameters unrelated to the state of the resource itself and use them as input to an action that has effects on the resource's state.

The response follows the same format as the related show endpoint (above), representing the resource's new state after the action has been applied.

Consult the reference documentation for specifics on any verb endpoints.