Dfyjkt

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

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