ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-308] 資源設計雜項 ​

定義和命名資源 ​

  • 應該(SHOULD)定義有用的資源。

    • 資源應該涵蓋90%的客戶端使用案例。一個有用的資源應該包含必要的資訊，但要盡可能精簡。為了支持剩餘的10%，允許客戶端通過支持過濾和嵌入來指定他們對更多/更少資訊的需求。

    • 示例:

      http
      /events
/users

  • 必須(MUST)使用特定領域的資源完整名稱。

    • API資源代表應用程序領域模型的元素。使用特定領域的命名法來命名資源有助於開發人員理解資源的功能和語義。例如，"sales-order-items"優於"order-items"，因為它清楚地表明了它所代表的業務對象。同樣，"items"太過籠統。

    • 示例:

      http
      /project-tasks
/financial-reports
/employee-records

  • 應該(SHOULD)模擬完整的業務流程。

    • API應該封裝完整的業務流程，包括代表該流程的所有資源。這有助於客戶端理解業務流程，促進一致的設計，並消除API之間的隱式依賴。此外，它還可以防止服務被設計成數據庫的薄包裝，這常常會將業務邏輯轉移到客戶端。

    • 示例:

      http
      /workflows
/workflows/{workflow-id}/steps
/workflows/{workflow-id}/actions

資源路徑設計 ​

  • 必須(MUST)通過路徑段識別資源和子資源。

    • 某些API資源可能包含或引用子資源。嵌入式子資源不是頂級資源，是更高級資源的一部分，不能在其範圍之外使用。子資源應該在路徑段中通過其名稱和標識符來引用，如下所示:

      http
      /resources/{resource-id}/sub-resources/{sub-resource-id}

      • 目標是創建直觀易懂的URL，其中每個子路徑都是對資源或一組資源的有效引用。例如，如果 /partners/{partner-id}/addresses/{address-id} 是有效的，那麼 /partners/{partner-id}/addresses， /partners/{partner-id}， 和 /partners 也應該是有效的。

      • 示例:

        http
        /orders/5678/items/1234
/orders/5678/items
/orders/5678
/orders

  • 可以(MAY)將複合鍵作為資源標識符暴露。

    • 如果一個資源最好由由多個其他資源標識符組成的複合鍵來識別，則允許在資源路徑中重用包含斜線的複合鍵的自然形式:

      http
      /resources/{compound-key-1}[delim-1]...[delim-n-1]{compound-key-n}

    • 路徑示例:

      http
      /tickets/{event-id}/{seat-number}
/tickets/{event-id}/{seat-number}/details
/assignments/{course-id}/{student-id}/grades
/assignments/{course-id}/{student-id}/submissions/{submission-id}

  • 可以(MAY)考慮使用(非)嵌套URL。

    • 如果子資源只能通過其父資源訪問，並且沒有父資源就可能不存在，請考慮使用嵌套的URL結構:

      http
      /projects/{project-id}/milestones/{milestone-id}

      • 如果資源可以通過其唯一ID直接訪問，那麼它應該作為頂級資源暴露:

        http
        /projects/1234
/milestones/5678

資源複雜性和層級 ​

  • 應該(SHOULD)限制資源類型的數量:

    • 為了保持可管理性和服務演進，遵循"功能分段"和"關注點分離"的設計原則。避免在同一API定義中混合不同的業務功能。努力限制通過API暴露的資源類型數量。例如，以下資源計為三種資源類型:學生、課程和學生相關課程。

      http
      /students
/students/{id}
/students/{id}/settings
/students/{id}/courses
/students/{id}/courses/{course-id}
/courses
/courses/{course-id}
      • /students 和 /students/id 都是 student 資源。
      • /students/{id}/settings 中的設置沒有標識符，不能脫離 student 而存在，它被視為 student 資源的一部分。
      • /students/{id}/courses 和 /students/{id}/courses/{course-id} 是 course 類型資源，與特定學生 /student/{id} 有1對1和1對多的關係。
  • 應該(SHOULD)限制子資源層級的數量:

    • 如果子資源的生命週期與主資源鬆散耦合，則使用子資源。你應該使用不超過三個子資源(嵌套)層級，因為更多的層級會增加API的複雜性和URL路徑長度。

    • 示例:

      不要這樣做

      http
      /libraries/{library-id}/books/{book-id}/chapters/{chapter-id}
/companies/{company-id}/departments/{department-id}/employees/{employee-id}