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

API Changelog ¶

Changelog is located at https://developer.productive.io/CHANGELOG.md

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 23 Oct 2021