Chapter 9. Designing Our API

In the last few chapters, we have followed a TDD approach to implement our Create User endpoint. However, a user directory application needs to do much more: retrieve, edit, delete, and search for users. In this chapter, we want you to practice what you've learned and implement these endpoints yourself.

To help you design an API that is easy to use, we will outline some principles of API design. Specifically, we will:

• Discuss what REST is, and what it is not
• Learn to design our API to be consistent, fast, intuitive, and simple
• Understand the different types of consistency: Common, Local, Transversal, Domain, and Perennial

What it means to be RESTful

When you read about APIs, you'll undoubtedly come across the terms SOAP, RCP, REST, and nowadays also GRPC and GraphQL. The status quo at the time of writing is that all APIs should be "RESTful," and any APIs that are not RESTful are considered subpar. This is a common misconception, which stems from the fact that many misunderstand what REST actually is. Therefore, we start this chapter by examining what REST is, what it is not, why it may not always be practical to use it, and why our API will not be RESTful.

What is REST?

REST stands for representational state transfer, and is a set of architectural styles that dictates the manners and patterns in which you construct your API. REST is nothing new; you are probably already well attuned to it because that's how the World Wide Web is structured, so don't let the terminology alienate you.

 

There are six requirements for REST:

• Client-server: Defines a clear separation of concerns (SoC) between client and server. The...

Designing our API

An application programming interface, or API, is the interface through which end users can interact with our application. For an API to work, both the client and the API server must agree on some form of mutually agreed convention, or contract; for a specific type of requests, the client can expect the API to reply with a specific type of response. But to have a "good" API, this contract must also be consistent, intuitive, and simple. Now, let's tackle each criterion one at a time.

Consistent

The principle of consistency is very important in API design. Arnaud Lauret, the author of the book The Design of Everyday APIs, elegantly outlined four different types of consistency in his blog post The four levels of consistency in API design (restlet.com/company/blog/2017/05/18/the-four-levels-of-consistency-in-api-design/), which we've summarized here:

• Common: Being consistent with the world
• Local: Being consistent within the same API
• Transversal: Being consistent across different...

Completing our API

In the previous chapters, we have shown you how to write unit, integration, and E2E tests as part of a TDD process. In this chapter, we've outlined the factors you should consider when designing an API. Now, we pass the baton to you to implement the rest of the API. Specifically, you should implement the following requirements:

• Delete
  • User must provide a user ID to delete
• Search
  • Defaults to the last 10 users who have registered
• Create
  • User must provide an email address and password
  • User may optionally provide a profile; otherwise, an empty profile will be created for them
• Retrieve
  • When a user provides a user ID of another user, the profile of that user should be returned
• Update
  • When a user provides a user ID and a complete user object, we should replace the old user object with the new one
  • When a user provides a user ID and a partial user object, we should merge the partial object into the existing object

 

 

Remember to also follow our existing conventions:

• All request data must...

Summary

In this chapter, we took a look at how to design and structure our API so that it is consistent, intuitive, and simple for our end users. We then left you to apply these principles as you implement the CRUD and search endpoints. In the next chapter, we will learn how to deploy our API on a cloud server, so that it's available to the world!