Partial responses

[nickevansuk]

Use Case

For mobile device usecases, a restricted number of fields returned enables the implementer to minimise data transfer.

References

• https://github.com/Haufe-Lexware/api-style-guide/blob/master/filtering-sorting-field-selection-and-paging/filtering-sorting-field-selection-and-paging.md#filtering
• https://blog.octo.com/en/design-a-rest-api/#filters
• https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data

Proposal

The fields keyword is reserved to allow for the restriction of properties returned in the response.

/sessions?fields=name,startDate,subEvent[1].startDate,subEvent[1].endDate

• A list of properties to be included, using dot notation
• Add limits to the number of items returned for properties where an array is available (note the limits are per-field, to allow the first item to contain more fields than subsequent items).
• If an object is specified without specific fields (e.g. location.address) return the whole object.

Examples

/sessions?fields=name,activity,location.address,offers.name,offers.price,offers.priceCurrency

  "items": [
    {
      "name": "Example Leisure Centre Table Tennis",
      "activity": "Table Tennis",
      "location": {
        "address": {
          "type": "PostalAddress",
          "streetAddress": "1 High Street",
          "addressLocality": "Bristol",
          "postalCode": "BS1 4SD"
        }
      },
      "offers": [
        {
          "name": "30 minute hire",
          "price": "10",
          "priceCurrency": "GBP"
        },
        {
          "name": "60 minute hire",
          "price": "10",
          "priceCurrency": "GBP"
        }
      ]
   }
 ]

/sessions?fields=name,activity,location.address.postalCode,offers[1].price,offers[1].priceCurrency,offers[2].name

  "items": [
    {
      "name": "Example Leisure Centre Table Tennis",
      "activity": "Table Tennis",
      "location": {
        "address": {
          "postalCode": "BS1 4SD"
        }
      },
      "offers": [
        {
          "name": "30 minute hire",
          "price": "10",
          "priceCurrency": "GBP"
        },
        {
          "name": "60 minute hire"
        }
      ]
   }
 ]

[lukehesluke]

@nickevansuk this looks good to me but have the following thoughts:

• For accessing across the items of an array, could use e.g. offers[].price (same syntax as in JQ https://stedolan.github.io/jq/manual/#Array/ObjectValueIterator:.[] )
• Comma separation of multiple terms should be consistent with strategy we go for in Filtering issue (https://github.com/openactive/opportunity-api/issues/1) w.r.t. multiple terms. e.g. it could be fields=name,activity, fields=name&fields=activity, fields[]=name&fields[]=activity, etc