As we have designed and implemented the PetSitter API, we’ve mostly looked at the happy path, which is when everything works according to plan and things are 200 OK. Obviously we want the interactions between our API and its users to be on this path as often as possible, but we cannot always guarantee that. In this chapter we’ll look at the ways things can go wrong and how to handle those situations.
The OpenAPI definition of an API is a contract that both sides, client and server, have to follow. If you look outside the field of technology and into contracts as legal documents, you’ll notice that they don’t just describe the happy path. In fact, the greater part of the legalese in the document usually describes all the potential problems and how to mitigate them. It’s when things go wrong that contracts are the most relevant. Error handling is equally important.
The same process that developers use to collaborate on the happy path, which includes designing schemas and API operations, can and should also guide their approach toward error handling. Each developer can bring their perspective to the table (and so can non-developers involved in the API design process).