[ADP-358] Partial Request

Overview

The main purpose of filtering is to add more flexibility to a collection for the user interface to decide what specific data to fetch. There are two aspects of filtering:

1. Result filtering: Filter the result by conditions (e.g., a=b, x>z)
2. Field filtering: Filter the result content by given keys only

Guidance

• SHOULD support filtering

  • Field filtering please refer ADP-311

• SHOULD use filters as payload for POST method since we recommend using payload for POST requests

  Note: To use the payload, it's not easy to design for value comparison. SHOULD design a new property parallel to filters

  POST /search
  {
    "filters": {
      "belongedCountry": "Taiwan",
      "shape": {
        "size": "SQUARE"
      }
    }
  }

Examples

Basic Filtering with Query Parameters

Please refer Filtering and Sorting

Complex Filtering with Request Body and Comparison Operators

Endpoint: POST /search

Request Body:

{
  "filters": {
    "category": "books",
    "price": {
      "gte": 10,
      "lte": 50
    },
    "author": "John Doe",
    "publishedAt": {
      "before": "2023-01-01"
    }
  }
}

Description: This request searches for books authored by John Doe, priced between 10 and 50 units, and published before January 1, 2023.

OpenAPI 3.1.0 Example

openapi: 3.1.0
paths:
  /search:
    post:
      summary: Search resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    category:
                      type: string
                    price:
                      type: object
                      properties:
                        gte:
                          type: number
                        lte:
                          type: number
                    author:
                      type: string
                    publishedAt:
                      type: object
                      properties:
                        before:
                          type: string
                          format: date
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Resource'

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        category:
          type: string
        price:
          type: number
        inStock:
          type: boolean
    User:
      type: object
      properties:
        id:
          type: integer
        age:
          type: integer
        signUpAt:
          type: string
          format: date
        status:
          type: string
    Resource:
      type: object
      properties:
        id:
          type: integer
        category:
          type: string
        price:
          type: number
        author:
          type: string
        publishedAt:
          type: string
          format: date
    Order:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string

Reference

Design references

• JSON API: Fetching Sparse Fieldsets