Productive V2 API
This api is implemented according to JSON API spec.
API Endpoint
The latest API endpoint is https://api.productive.io/api/v2
Content Negotiation
Content-Type
header must be set to application/vnd.api+json
.
While sending bulk requests, make sure to set Content-Type
to application/vnd.api+json; ext=bulk
.
When Content-Type
is not set as described, API will return 415 response status error.
Authorization
Most resources have authorization on them. If successfully authorized, you will get a response containing the resource; however, if you aren’t authorized then you will be given HTTP status of 401, and an error message.
Authentication
To authenticate yourself, add your API token to the X-Auth-Token header for every request.
To access your organization data, add your organzation ID to the X-Organization-Id header for every request.
Pagination
Pagination has to be set in the following style:
?page[number]=2&page[size]=20
Where page[number]=
is the page you want to view, and page[size]=
is the number of resources you want to return.
Filtering
If you would like to add filtration to your query, you can do that by setting the supported filter parameters in the following way: ?filter[person_id]=24
.
In case you set filter parameter that is not supported for the query, you will get 400 status error:
{
"errors": [
{
"status": 400,
"title": "Unsupported Filter",
"detail": "Filter 'undefined' is not supported on this endpoint"
}
]
}
Filter Operations
There is also support for different filter operations. Allowed operations are:
-
eq
-
not_eq
-
contains
-
not_contain
-
gt
-
gt_eq
-
lt
-
lt_eq
To use operations for filtering, define it after the param name: ?filter[person_id][not_eq]=24
.
NOTE: Not all endpoints support filter operations. If an endpoint supports filter operations, it will be listed in the documentation for that endpoint.
Sorting
To sort query results, you can use sort parameter, passing available sort params for the resource: ?sort=name
.
All available sort params are defined separately for each resource. You can provide desired sort order using -
sign (?sort=-name
), where no -
defines ascending and -
defines descending order by the given sort parameter.
If a given parameter is not supported, Unsupported Sort
error (with status 400) will be raised:
{
"errors": [
{
"status": 400,
"title": "Unsupported Sort",
"detail": "Sort by 'unsupported' is not supported on this endpoint"
}
]
}
Aggregation
Some endpoints have available ?aggregates
param. All available aggregation params are listed under each resource. In the case when aggregates
param is present in the query, meta
property of the response will include aggregates
property with requested fields included (if available).
If a given parameter is not available for the resource, Unsupported Aggregate
error will be raised:
{
"errors": [
{
"status": 400,
"title": "Unsupported Aggregate",
"detail": "Aggregate 'unavailable' is not supported on this endpoint"
}
]
}
Errors
400
Used when a given query param is not supported.
Possible title values: Unsupported Filter, Unsupported Filter Value, Unsupported Sort, Unsupported Aggregate, Unsupported Group
{
"errors": [
{
"status": 400,
"title": "*one of listed values*",
"detail": "*...* is not supported on this endpoint"
}
]
}
401
{
"errors": [
{
"status": 401,
"title": "Unauthenticated",
"detail": "You are not authenticated"
}
]
}
403
{
"errors": [
{
"status": 403,
"title": "Access Denied",
"detail": "You are not authorized to access this resource"
}
]
}
404
{
"errors": [
{
"status": 404,
"title": "Record Not Found",
"detail": "The requested record was not found"
}
]
}
406
{
"errors": [
{
"status": 406,
"title": "Not Acceptable",
"detail": "The request was not accepted"
}
]
}
415
{
"errors": [
{
"status": 415,
"title": "Unsupported Media Type",
"detail": "Unsupported content type"
}
]
}
422
{
"errors": [
{
"status": 422,
"title": "Invalid Attribute",
"detail": "Unsupported content type"
}
]
}
500
{
"errors": [
{
"status": 500,
"title": "Server Error",
"detail": "An error occured on the server"
}
]
}
Generated by aglio on 14 Apr 2021