Resource Representation ¶

Response format ¶

The response format is JSON API. It is a JSON object with:

• a required data key, which contains the requested resources

• an optional meta key, which contains information about the response

• an optional links key, which contains links for pagination

• an optional included key, which contains data of related resources

The data key can contain a single resource or an array of resources.

Example:

{
  "data": {},
  "meta": {},
  "links": {},
  "included": {}
}

Resource ¶

A resource is an object representing a single entity in the system. It is identified by its type and ID and contains attributes and relationships.

Attributes ¶

Attributes are the properties of a resource that are not relationships. They can be any valid JSON value.

Relationships ¶

Relationships are references to other resources that are associated with the current resource. By default, information about these relationships is not included.

Example: ¶

{
  "data": {
    "id": "1",
    "type": "tasks",
    "attributes": {
      "name": "Task 1",
      "description": "This is a task",
      "due_date": "2023-01-01"
    },
    "relationships": {
      "creator": {
        "meta": { "included": false },
      },
      "project": {
        "meta": { "included": false },
      },
      "parent_task": {
        "meta": { "included": false },
      }
    }
  }
}

Including relationships ¶

To include relationships in the response, you must pass an include query parameter which contains a comma-separated list of the desired related resources: ?include=creator,project.project_manager. This will:

1. Include the identifier data (ID and type) to the relationships section of the resource.

2. Include the requested relationship data in the included section of the response.

3. If a dot notation is used, it will include the data of the related relationship as well.

If requested resources does not exist, Unsupported Include error (with status 400) will be raised:

{
    "errors": [
        {
            "status": 400,
            "title": "Unsupported Include",
            "detail": "Include 'userz' is not supported on this endpoint"
        }
    ]
}

If include query parameter is not provided, the response will not include included section.

Example: GET http://api.productive.io/api/v2/tasks?include=creator,project.project_manager

{
  "data": {
    "id": "1",
    "type": "tasks",
    "attributes": {
      "name": "Task 1",
      "description": "This is a task",
      "due_date": "2023-01-01"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1",
          "type": "people"
        }
      },
      "project": {
        "data": {
          "id": "1",
          "type": "projects"
        }
      },
      "parent_task": {
        "meta": { "included": false }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "people",
      "attributes": {
        "name": "John Doe",
        "email": "john@doe.com"
      }
    },
    {
      "id": "1",
      "type": "projects",
      "attributes": {
        "name": "Project 1",
        "description": "This is a project"
      },
      "relationships": {
        "project_manager": {
          "data": {
            "id": "1",
            "type": "people"
          }
        },
        "workflow": {
          "meta": { "included": false }
        }
      }
    }
  ]
}

In the example above, the request asked for the creator and project.project_manager relationships. The included section contains just one “person” because the same person is the creator of the task and also the project_manager of the project and is only included once. Since parent_task was not requested, its data is not included. Also note that to get the workflow relationship, the include query parameter must contain project.workflow, as workflow is a relationship of the project and not of the task.

Sparse fields ¶

To return a subset of fields of a resource in the response, you must pass an fields query parameter which contains an hash of resource types with a comma separated list of wanted fields: ?fields[people]=name,last,company. The wanted fields can be any attribute or relationship of a resource. Fields can also be attributes of a relationship resource, not just the main resource. If requested field does not exist, backend will ignore that non-existing fields, but will work with others existing fields. It can also be used with include query parameter.

For example: GET http://api.productive.io/api/v2/tasks?fields[tasks]=title,creator&fields[people]=first_name,date&include=creator results in:

{
  "data": {
    "id": "1",
    "type": "tasks",
    "attributes": {
      "title": "Task 1"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1",
          "type": "people"
        }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "people",
      "attributes": {
        "first_name": "John"
      }
    }
  ]
}

NOTE: If include query contains a relationship that is not present in the fields query, the response will include the relationship in the included section, but you will not be able to link it to the right resource.