API REST с использованием спецификации RAML: как указать общее количество страниц в ответе - PullRequest
Новая
       18

API REST с использованием спецификации RAML: как указать общее количество страниц в ответе

0 голосов
/ 12 ноября 2018

Я не уверен, как 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', чтобы можно былодобавить свойство totalpages для ответа.

Это правильный способ, как это сделать?

Я также читал, что можно использовать пользовательский заголовок http (x-total-pagesили что-то в этом роде).

Я на самом деле вроде бы не хотел, чтобы в API были все типы оболочек ... Кто-нибудь знает, что является стандартом для этого?

Спасибомного заранее за ваши ответы.Sergio

1 Ответ

0 голосов
/ 15 ноября 2018

Вы можете инкапсулировать все разбитые на страницы черты в trait и использовать их во всех доступных для просмотра ресурсах, используя is.Поскольку ресурсом с возможностью просмотра страниц обычно является GET / collectionresource, вы также можете добавить признак для заголовка ответа 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

raml2html output

...