Back to top

Common Parameters

The Packet API uses a few methods to minimize network traffic and bandwidth:

include

For resources that contain collections of other resources, the Packet API will return links to the other resources by default.

{
  ...
  // Includes "href" links if the resource is reachable through the API.
  "projects": [
    { "href": "/projects/5b590e4f-be96-4400-ae32-c315ee67964d" },
    { "href": "/projects/f3f131c8-f302-49ef-8c44-9405022dc6dd" }
  ],
  // Includes "id" attributes if not.
  "emails": [
    { "id": "eb5d8c89-4d15-4c87-859c-5ae190ad5d9a" },
    { "id": "c17f77ad-9070-4084-abaa-7538581d9523" }
  ]
  ...
}

However, if you're interested in acting on resources in the projects collection, it doesn't make sense to make a separate API call to retrieve each project. Instead, you can specify which collections you'd like to be included using the include parameter.

/user?include=projects

will return

{
  ...
  "projects": [
    {
      "href": "/projects/c851d3c5-d55d-4b1a-99f1-96fc64768bc3",
      "id": "c851d3c5-d55d-4b1a-99f1-96fc64768bc3",
      "name": "Project 1",
      ...
    },
    {
      "href": "/projects/21f8e88b-bd4e-44ca-b956-4f3f88e6e5f2",
      "id": "21f8e88b-bd4e-44ca-b956-4f3f88e6e5f2",
      "name": "Project 2",
      ...
    }
  ],
  ...
}

The include parameter is accepted for all GET requests on all resources and collections, and should be specified as a comma-separated list.

/user?include=emails,projects,memberships

You may also include nested associations up to 3 levels deep using dot notation:

/user?include=memberships.projects