[ADP-358] 部分請求

概述

過濾的主要目的是為用戶界面增加更多靈活性，以決定獲取哪些特定數據。過濾有兩個方面:

1. 結果過濾: 通過條件過濾結果(例如，a=b，x>z)
2. 屬性過濾: 僅通過給定的鍵過濾結果內容

指導

• 應該(SHOULD)支持過濾

  • 使用 GET 的過濾請參照 Filtering。

• 應該(SHOULD)使用 filters 作為 POST 方法的負載，因為我們建議對 POST 請求使用負載

  注意:使用負載時，設計值比較並不容易。應該設計一個與 filters 平行的新屬性

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

示例

使用查詢參數的基本過濾

請參閱 Filtering以及Sorting。

使用請求體和比較運算符的複雜過濾

端點: POST /search

請求體:

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

描述: 此請求搜索由 John Doe 撰寫，價格在 10 到 50 單位之間，並在 2023 年 1 月 1 日之前出版的書籍。

OpenAPI 3.1.0 示例

openapi: 3.1.0
paths:
  /search:
    post:
      summary: 搜索資源
      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: 成功回應
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Resource'
  /orders:
    get:
      summary: 檢索訂單
      parameters:
        - name: status
          in: query
          schema:
            type: string
          description: 按訂單狀態過濾
      responses:
        '200':
          description: 成功回應
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'

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

參考

設計參考

• JSON API: 獲取稀疏屬性(property)集