API: Signaling

Some endpoints, especially those returning Collection resources, support signaling desired properties. By signaling, the client can convey to the server the properties to include in a response.

Currently only select is supported which allows to specify the subset of properties a client is interested in. The benefit of using select is reduced response time. Other signaling, especially expanding the embedded resources to include as well over multiple layers of embedding are in consideration to be implemented (probably named embed) but as of now, they are not supported. Please also see the specification for OData that inspired this feature.

For example, a resource /api/v3/bogus that without signaling returns:

  {
    "_type": "Collection"
    "count": 20,
    "total": 554,
    "_embedded": {
      "elements": [
        {
          "id": 1,
          "name": "Some name"
        },
        {
          "id": 9,
          "name": "Another name"
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/v3/bogus",
        "title": "A bogus collection"
      },
      "bar": {
        "href": "/api/v3/bar",
        "title": "Foobar"
      }
    }
  }

can via signaling /api/v3/bogus?select=total,elements/name,bar be instructed to return:

  {
    "total": 554,
    "_embedded": {
      "elements": [
        {
          "name": "Some name"
        },
        {
          "name": "Another name"
        }
      ]
    },
    "_links": {
      "bar": {
        "href": "/api/v3/bar",
        "title": "Foobar"
      }
    }
  }

The select query property is a comma separated list of the properties to include, e.g. select=total,elements/name,bar. The API also accepts alternative styles of writing like select=["total","elements/name","bar"]. Each individual item in the list is the path inside the resource. So while total refers to the property on the top level, elements/name refers to the property name within the collection of elements. The full path has to be provided for every property, e.g. select=elements/name,elements/id. The order of the list has no impact on the selection. There is also a wildcard * which will result in every property on that level to be selected. To select every property in the example above, the client would have to signal select=*,elements/*.

Please note that the nesting into _embedded and _links is not included in the query prop select as links in the context of HAL can be considered properties of the resource just the same as unnested properties and forcing clients to write the full nesting would not increase clarity.

Link properties are considered to be a single value that cannot be split up further. Every property within a link will be returned if the link is signaled to be selected.

The select signaling flag has been introduced for performance reasons. Not every end point supports it and those that do oftentimes only allow a subset of their resource’s properties to be selected. End points supporting the select query prop are documented accordingly.