REST API 使用 RAML 规范：如何在响应中指定 total-pages

Question

我不确定 REST API 在分页方面应该如何设计。

这是我的例子：

#%RAML 1.0
title: Test Api Documentation
description: Test Api Documentation
baseUri: https://localhost/
version: v0.1
protocols: [ HTTPS ]
mediaType: [ application/json ]
documentation:
  - title: Test API for REST Client
    content:
      "Test API for REST Client."
types:
  Thing:
    type: object
    properties:
      name: string
      age: number
      color: string
  Things:
    type: object
    properties:
      things?: Thing[]
      totalPages?:
        type: integer
        format: int64
/things:
  get:
    headers:
      Cookie:
        type: string
    responses:
      '200':
        description: OK
        body:
          application/json:
            type: Things
      '401':
        description: Unauthorized
      '404':
        description: Not Found
    queryParameters:
      page:
        description: page
        required: false
        type: integer
        format: int32
      pageSize:
        description: pageSize
        required: false
        type: integer
        format: int32

有此包装类型 'Things' 能够为响应添加总页数属性。

这是正确的方法吗？

我还了解到可以使用自定义 http header（x-total-pages 或类似内容）。

我实际上有点不喜欢在 API... 有人知道这是什么标准吗？

非常感谢您的回答。塞尔吉奥

Answer 1

您可以将所有分页特征封装到一个 trait 中，并使用 is 在所有可分页资源中使用它。由于可分页资源通常是 GET /collectionresource，您还可以为响应 header X-TOTAL-PAGES 添加一个特征，用于 200 个响应 paginated.

示例：

#%RAML 1.0
baseUri: https://mocksvc.qax.mulesoft.com/mocks/8ab3d909-11e0-4f1d-aaef-bef029b83fbf
title: paginated api
mediaType: application/json
protocols: [ HTTP ]
traits:
  paginated:
      queryParameters:
        page:
          description: page
          required: false
          type: integer
          format: int32
        pageSize:
          description: pageSize
          required: false
          type: integer
          format: int32    
      responses:
        200:
          headers:
            x-total-pages:  
types:
  Thing:
    type: object
    properties:
      name: string
      age: number
      color: string
  Things:
    type: object
    properties:
      things?: Thing[]

/things:
  get:
    is: [ paginated ]
    responses:
      '200':
        description: OK
        body:
          application/json:
            type: Things
      '401':
        description: Unauthorized
      '404':
        description: Not Found

REST API 使用 RAML 规范：如何在响应中指定 total-pages

REST API using a RAML specification: how to specify total-pages in response

api

rest

raml