Our API follows a subset of the JSON:API specification.
As such, there are several predictable ways all endpoints will behave.
Developers are encouraged to use JSON:API-compatible tools and libraries when working with our API.
Content types
When making requests to resource endpoints, your client should specify the Accept: application/vnd.api+json
request header.
In addition, requests with bodies (e.g. POST, PATCH) should include the header Content-Type: application/vnd.api+json
.
All API endpoints which represent resources will respond with the header Content-Type: application/vnd.api+json
.
The response content-type has one parameter, ext="https://api.getpylon.com/jsonapi"
which describes our extensions to the spec (see below).
Single resources
A response body representing a single resource will contain a data
property which is an object containing the resource.
All resources contain type
, id
, attributes
and relationships
, and usually contain links
.
Collection resources
A response body representing a collection of resources will contain a data
property which is an array of resource objects.
Each object in the array is identical to the individual resource object described above.
See the example belowto the right
for an illustration of a typical response body.
Filtering response fields
If you want to reduce the size of response bodies from the API—for example, if you are only interested in one field, not the rest of the response—you may use JSON:API sparse fieldsets to filter response bodies.
The general format is to provide a query parameter fields[type]=field1,field2
where the type
is the type of an object included in the response body, and field1
and field1
are names of either attributes or relationships of the object.
For example, here is URL for a request to the users API which filters the response fields.
https://api.getpylon.com/v1/users?fields[users]=email
In the response to this request, all objects of the users
type will only contain an email
attribute, and no relationships:
Pagination
A response body representing a collection will have pagination links in a top-level links
property.
It will contain information about the entire collection (e.g. its total size) in a top-level meta
property.
You should not construct paginated URLs manually! Use the links
!