Outline
Creating REST based API's is a thankless job but is of particular importance when creating production ready applications. There are few resources available online that will teach you how to design robust API specifications that your backend & frontend can adhere to, and they often don't show a real world example of this.
In this course, we'll be creating an API spec based on the desired functionality of "Conduit," a social blogging platform similar to Medium. We recommend spending a minute getting familiar with Conduit's functionality before proceeding with this tutorial, as our API spec revolves around it.
There is no definitive way to design an API -- it mostly comes down to industry best practices, the developer's previous experience & taste, and specific project requirements. While there have been a handful of attempts to standardize the design of JSON based API's, none have gained critical adoption across the entire development community. JSON API is one proposed standard, but many developers feel that it is verbose and is better suited for large organizations.
It's not just about creating endpoints; it's also about creating standard data structures, status codes, error handlers, and naming schemes that will be consistently used for transmitting & receiving data.
Designing an API usually comes in two steps:
- Specifying uniform data structures, status codes, error handlers, and naming schemes that are consistently used across the API
- Creating intuitive endpoints to transact those data structures, status codes, and error handlers
Let's get started!