Query Parameters

The expand parameter

A resource might be hierarchical and include parent-child relationships. For example, a deployment contains a summary and one or more versions. Each version can be represented as a separate resource so that a client can directly handle a version. For performance reasons, when a client issues a GET request against the parent resource, only links to the child resources are returned by default. For example:

{
  "name": "Example",
  "description": "Description of Example Project",
  "compatibilityMode": "latest",
  // ...
  "versions": {
    "links": [
      // links ...
    ]
  },
  "logs": {
    "links": [
      // links ...
    ]
  },
  "links": [
    // links ...
  ]
}

The expand query parameter provides the client an option of getting the child resources in line with its parent. For example, send GET /api/12.2.10/deployments/Example?expand=versions to get the versions child resources along with its summary:

{
  "name": "Example",
  "description": "Description of Example Project",
  "compatibilityMode": "latest",
  // ...
  "versions": {
    "items": [
      {
        "description": "Ad hoc project 'Example'. Deploy again.",
        "versionNo": 5,
        "addedBy": "admin",
        "activeVersionFlag": false,
        // ...
      },
      // more versions ...
    ],
    "links": [
      // links ...
    ]
  },
  "logs": {
    "links": [
      // links ...
    ]
  },
  "links": [
     // links ...
  ]
}

If multiple child resources are to be expanded, then comma , is used to separate the names of the children, such as ?expand=versions,logs.

Finally, a client can use ?expand=all to get all the child resources.

The fields parameter

This query parameter is used to specify what fields should be returned. For example, given a response that consists of several fields:

{
  "name": "Example",
  "description": "Description of Example Project",
  "compatibilityMode": "latest",
  "services": [
    // ...
  ],
  // ...
  "links": [
    // links ...
  ]
}

A fields parameter specification of ?fields=name,description only returns name and description fields:

{
  "name": "Example",
  "description": "Description of Example Project",
  "links": [
     // links ...
  ]
}

Comma , is used to separate multiple field names. The links field is always returned.