Productive V2 API

API Endpoint

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 10 Aug 2020