3

When designing a REST API, following guidance such as 10 Best Practices for Better RESTful API, there seem to be all sorts of ways to provide a query syntax, pagination, selecting fields to return, etc.

For example, some ways to do pagination:

  • /orders?max=20&start=100
  • /orders?per_page=20&page=5

Some ways to provide a query interface:

  • /orders?q=value>20
  • /orders?q={'value': 'gt 20'}

Are there any standards for how to design an API that offers these features? If not, standards in development or best practice guidelines would be useful.

paj28
  • 2,210
  • 3
  • 25
  • 37
  • The answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise, that is *primarily opinion-based*. Just pick the format that suits you better, provide some documentation and use it. – cassiomolin Feb 03 '16 at 14:16
  • 5
    @CássioMazzochiMolin - "is there a standard format" is an objective question. Your comment implies the answer is no. I'd be surprised if there's nothing - but I'm struggling to find anything. – paj28 Feb 03 '16 at 14:27
  • AFAIK, there are *good practices*, not *standards*. – cassiomolin Feb 03 '16 at 14:30
  • 1
    @CássioMazzochiMolin - thanks. RFC 6902 provides a standard for a JSON PATCH operation. Would have thought there's something similar for query? – paj28 Feb 03 '16 at 14:33
  • RFCs 7230 to 7235 cover the HTTP protocol, but no standard for filtering, field selection and pagination in REST APIs is defined. The RFC 5005 defines a standard for feed paging and archiving, but that's not what you want. – cassiomolin Feb 03 '16 at 14:43

1 Answers1

3

When researching this for the Watson Discovery and Assistant APIs, we weren't able to find any widely adopted conventions for filtering or paging, although there are many different conventions.

Some considerations for which convention you use:

Do you need compound clauses in your query? If you want to be able to express a > 10 || b < 10, then you need a string syntax or structured JSON structure to represent the more complicated queries, which will likely be a usability challenge for your users, and so is preferable to avoid if you don't really need the flexibility. In general, the simpler you can keep the requirements, the easier the API will be to learn and use, while potentially at the expense of flexibility. For example, if it turns out that the created date is the only field that users actually care about doing inequality filtering on, you could have explicit begin_date and end_date filter parameters instead of allowing inequality comparisons on all fields.

For pagination, do you have frequently changing data? If so, paging by offset may give you unstable results. For example, paging through logs that are actively being created, sorted by most recent, would cause you to see duplicate items. To avoid this, the server can return a token that represents the next page. This token can either be a lookup value or directly encode the information necessary to identify the values of the next item in the potentially changing list. Microsoft's API guidelines contain examples of both token and offset based paging, and are one of many sets of conventions to follow: https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#98-pagination

Jeffrey Stylos
  • 163
  • 7