Search code examples
restapiraml

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

I am not sure about how the REST API should be designed in terms of pagination.

Here's my example:

#%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

There is this wrapper type 'Things' to be able to add the totalpages property for the response.

Is this the right way how to do it?

I've also read that a custom http header can be used (x-total-pages or something like that).

I actually kind of don't like to have all the wrapper types in the API... Does anybody know which is the standard for this?

Thanks a lot in advance for your answers. Sergio

Solution

  • You can encapsulate all the paginated traits into a trait and use that across all you pageable reosources using is. As pageable resource are typically GET /collectionresource, you can also add a trait for the response header X-TOTAL-PAGES for 200 responses that are paginated.

    Example:

    #%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