manning online
The Design of Web APIs, Second Edition cover
welcome to this free extract from
The Design of Web APIs, 2nd
an online version of the Manning book.
to read more
or

9 Designing user-friendly, interoperable operations

 

This chapter covers

  • Designing easy-to-use requests and responses
  • Filtering, sorting, and paginating lists
  • Handling multiple data formats
  • Erroring gracefully
  • Avoiding hiding capabilities
  • Standardizing operations

Imagine a Shopping API whose “Create order” (POST /orders) operation returns 400 Bad Request without further explanation for any error, such as a typo in a property name (qantity instead of quantity), an invalid product reference, or an unavailable product. Developers will have difficulty figuring out the problem in their code, or end users may face an unhelpful “Impossible to validate order” message.

And it’s not only error-handling that can be problematic. Despite a valid purpose, an operation’s HTTP representation, requested and returned data, and behavior can increase development time, code complexity, and error risk, and can even affect end users. Designing user-friendly, interoperable operations prevents these problems, making developers more efficient and leading them to love the API.

9.1 What makes operations user-friendly and interoperable?

9.1.1 User-friendly operations expose clear capabilities that meet the needs

9.1.2 User-friendly operations use user-friendly data and are helpful

9.1.3 User-friendly, interoperable operations are consistent and standard

9.2 When and how to design user-friendly, interoperable operations

9.2.1 When to take user-friendly, interoperable operations into consideration

9.2.2 How to design user-friendly, interoperable operations

9.3 Designing easy-to-understand, guessable operations

9.3.1 Combining meaningful resource paths and HTTP compliance

9.3.2 Creating predictable resource paths

9.3.3 Crafting short but accurate resource paths

9.4 Requesting easy-to-provide inputs

9.4.1 Using typical and HTTP-compliant input locations

9.4.2 Mapping inputs to outputs

9.4.3 Requesting well-known or standard data

9.4.4 Minimizing inputs with default and server-processed data

9.5 Returning ready-to-use successful responses

9.5.1 Choosing adequate HTTP status and HTTP-compliant data locations