[ADP-313] Sorting

reviewing phase 1

Add sort to common components.parameters

Guidance

• MUST document API support for sorting.
• MUST use the common query parameter sort.
• MUST use - to represent descending sorting order. No sign means ascending by default.
• MUST use a comma-separated list to represent multiple sorting criteria.
• SHOULD support sorting for all collection resources.
• SHOULD limit the number of fields that can be sorted to prevent performance issues.

Design Considerations

• + in URLs would be encoded, so we omit it for ascending order.
• Consider performance implications when allowing sorting on multiple fields.
• Clearly document the default sorting behavior when no sort parameter is provided.

Examples

• Get the applications list sorted by ascending appName (A to Z) and then descending releaseDate:

  GET /applications?sort=appName,-releaseDate

• Sort users by last name (ascending) and then by age (descending):

  GET /users?sort=lastName,-age

OpenAPI 3.1.0 Example

openapi: 3.1.0
info:
  title: Example API
  description: An example API for demonstrating sorting
  version: 1.0.0
paths:
  /applications:
    get:
      summary: Get a list of applications
      parameters:
        - name: sort
          in: query
          description: Sort the list of applications
          schema:
            type: string
            example: appName,-releaseDate
          required: false
      responses:
        '200':
          description: A list of applications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
  /users:
    get:
      summary: Get a list of users
      parameters:
        - name: sort
          in: query
          description: Sort the list of users
          schema:
            type: string
            example: lastName,-age
          required: false
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    Application:
      type: object
      properties:
        appName:
          type: string
        releaseDate:
          type: string
    User:
      type: object
      properties:
        lastName:
          type: string
        age:
          type: integer

Implementation Details

• Implement server-side sorting to ensure consistent results across different client requests.
• Use appropriate indexing on database fields commonly used for sorting to optimize query performance.
• Handle invalid sorting parameters gracefully, returning a 400 Bad Request with a clear error message.

Security Considerations

• Validate and sanitize sort parameters to prevent potential SQL injection attacks.
• Consider implementing rate limiting for complex sorting operations to prevent DoS attacks.

Related ADPs

• [ADP-311] Filtering
• [ADP-312] Pagination

References

• JSON API - Sorting
• Zalando API Guidelines