[ADP-359] Partial Response

Guidance

• SHOULD support result field filtering by common query parameter: fields

  GET /locations?fields=(name,id) HTTP/1.1
  GET /nations?fields=(fieldlevel1(fieldlevel2)) HTTP/1.1
  GET /results?fields=!tag
  GET /employees?fields=!(fieldlevel1(fieldlevel2), fieldlevel1_2)

• SHOULD return 200 OK since 206 Partial Content is specifically for Range Requests.

BNF rules

<fields>            ::= [ <negation> ] <fields_struct>
<fields_struct>     ::= "(" <field_items> ")"
<field_items>       ::= <field> [ "," <field_items> ]
<field>             ::= <field_name> | <fields_substruct>
<fields_substruct>  ::= <field_name> <fields_struct>
<field_name>        ::= <dash_letter_digit> [ <field_name> ]
<dash_letter_digit> ::= <dash> | <letter> | <digit>
<dash>              ::= "-" | "_"
<letter>            ::= "A" | ... | "Z" | "a" | ... | "z"
<digit>             ::= "0" | ... | "9"
<negation>          ::= "!"

Example

GET /jobs?fields=(name, id) HTTP/1.1

HTTP/1.1 200 OK
{
    jobs: [{
      id: 'uuid-',
      name: '...'
    }]
}

OpenAPI 3.1.0 Example

openapi: 3.1.0
info:
  title: Partial Response API
  version: 1.0.0
paths:
  /jobs:
    get:
      summary: Get jobs with field filtering
      parameters:
        - in: query
          name: fields
          schema:
            type: string
          description: Fields to include in the response
          example: "(name,id)"
      responses:
        '200':
          description: Successful response
          content:
            application/json:    
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                required:
                  - jobs

components:
  parameters:
    FieldsParameter:
      name: fields
      in: query
      description: Fields to include in the response
      schema:
        type: string
      example: "(name,id)"

Best Practices

1. Implement proper error handling for invalid field requests.
2. Consider performance implications when allowing complex field filtering.
3. Document the supported fields and any limitations in the API documentation.
4. Use caching strategies to improve performance for frequently requested field combinations.

References

• Google API Design Guide - Partial Response
• Microsoft API Guidelines - Query Parameters

Changelog

• 2024.09.19 Remove outdated microsoft guideline link.