The Fields Pattern in REST API Design

The Fields Pattern or Field Selection Pattern for REST API design is a useful approach whenever the representations returned from the API become quite large and the API can be used by many clients in different contexts. For example, a native app client may only require a select few fields from the usual resource representation.

Suppose we have a resource employees, with employee representations containing a large number of fields. With the fields pattern, a client could make a request of the form:

GET /employees?fields=name,role,salary

The API will respond to this request with only these fields in addition to id:

{
   "id": "12345",
   "name": "John Smith",
   "role": "Developer",
   "salary": "100,000K"
}

A different client can request a different selection of fields:

GET /employees?fields=projectId,address
{
   "id": "12345",
   "projectId": "6789",
   "address": {
      "streetName": "REST Avenue",
      "postalCode": "J6V 9M2",
      "city": "Toronto"
   }
}

It is also possible to omit the id field, though arguably a resource representation should always have its primary identifier present, even when selecting fields.

If the fields parameter is omitted, the API responds with all fields of the employee resource available.

What if we want to be able to select fields of sub-objects, such as the address object? There are several options, for example:

GET /employees?fields=address:city

GET /employees?fields=address.city

GET /employees?addressFields=city

However, none of these are fully satisfying and venture into inventing syntax. Almost certainly, no two API designs will select the same syntax, and so none of these are ideal for a natural, simple design.

Selection of fields on arbitrarily complex objects is one of the many elegant, standard solutions provided by GraphQL, so a GraphQL API design may be preferable in cases where complex multi-level field selection is desired.