This content originally appeared on Level Up Coding - Medium and was authored by Ikdem Ben Mbarek
Design Developer-friendly RESTful APIs
What do we use APIs for?
We live in the era of APIs, in an era where we pay for data more than we pay for oil. To get that immense data from the database to your display, it needs to go through a server that makes it accessible on the Internet thanks to APIs. You just send the right request with the right query and method to the right endpoint and you get the data you want. This data can be anything from pokemon names and types, to weather predictions, and even sports bets and political and business news.
Now if 2 humans want to communicate, they should have a common language to avoid turning into 2 miming homo sapiens. Let alone if we’re talking machines. Communication through the Internet follows countless Protocols, one of them is HTTP, the protocol used to exchange data in the form of HTTP requests and responses. RESTful APIs, the “standard” for APIs nowadays, is built upon HTTP and JSON.
Why should we follow the API design patterns?
If you’re a full-stack developer that is working on a small scale application by himself, this would look odd for you. But out there in the industry, it’s almost impossible to find someone working both as a frontend and a backend developer, at least not on the same project. This means that you can find 2 people, from 2 distant continents, working on the same project. One would be creating the API and handling the upcoming requests, while the other would be consuming the API and sending the requests. This, of course, cannot be real if they do not have some common patterns to work with.
RESTful API Design Patterns
We will go through what a Backend developer should do to make his API comprehensible and accelerate the development process. Also, it will help make your API live longer and be used by more developers from around the world.
URI Formats
- Use forward slash (/) seperator
This is used to indicate the hierarchical relationship between resources - Don’t use a trailing forward slash
Avoid having a trailing slash at the end of your API as it only causes confusion and does not have any significant meaning.
http://xx.yy.zz/shapes/polygons/
- Use Hyphens (-) Avoid underscores (_)
Hyphens improve the readability of URI names, paths, and segments, and help clients to scan and interpret easily. You should avoid underscores in the path, as the character may be partially obscured or hidden while rendering on visual cues due to computer fonts. Also, there is the risk of being ignored by the Google search engine. - Stick to lowercase letters
RFC 3986 defines URIs as case sensitive except for the scheme and host components. That’s why you should give preference to lowercase usage. Also, notice how I (capital i) and l (lowercase L) are quite similar. This has been largely used by hackers to trick people into fake websites.
http://xx.yy.zz/shapes/polygons
HTTP://XX.YY.ZZ/shapes/polygons // same as previous
http://xx.yy.zz/shapes/polygons
HTTP://XX.YY.ZZ/SHAPES/Polygons // different than previous
Carefully use HTTP Methods
HTTP methods have their names for a reason. You should use:
- GET in case we’re fetching or reading Data
- POST in case we’re creating new data
- PUT in case we’re updating a whole resource in our data with a new one
- PATCH in case we’re partially updating a resource
- DELETE in case we’re deleting existing data
Formulate well your endpoints
Developers tend to be very confused about how to name their endpoints. Here are a few rules you should follow when you’re using REST.
- Include version numbers
It may not seem that obvious now, but one day, you’ll feel that your API structure can’t handle your system and can’t scale up anymore. That’s where you‘ll be seriously thinking about building everything from bottoms up again: new models, new entities, new controllers, new endpoints, … Such big migration will need a new version for your API. That’s why it’s wise to include the version number at the start of your endpoints. This way, you’ll still be able to handle legacy requests while scaling up and systems built with your API won’t crash. - Use consistent sub-domain names
Consistent sub-domains should be provided to developers if you want them to consume and test your API:
api.amazing-app.com // for api requests
dev.amazing-app.com // for development environment
- Use nouns rather than verbs. Let the HTTP methods do the action
Request methods are significative and should give an idea about the action needed by the request.
GET http://api.example.com/v1/users // DO
GET http://api.example.com/v1/users/get-users // DONT
POST http://api.example.com/v1/users // DO
POST http://api.example.com/v1/users/create-user // DONT
PUT http://api.example.com/v1/users/:id // DO
PUT http://api.example.com/v1/users/update-user/:id // DONT
DELETE http://api.example.com/v1/users/:id // DO
DELETE http://api.example.com/v1/users/delete-user/:id // DONT
DELETE http://api.example.com/v1/users/1234 // DO
GET http://api.example.com/v1/delete-user?id=1234 // DONT
POST http://api.example.com/v1/1234/delete // DONT
Use singular nouns for document names and plural names for collections and stores.
http://api.example.com/v1/profiles/customers
http://api.example.com/v1/profiles/customers/memberstatus
http://api.example.com/v1/profiles/customers/memberstatus/preferences
It is possible to use a verb or a verb phrase for controller resources.
http://api.example.com/v1/profiles/customers/memberstatus/reset
http://api.example.com/v1/profiles/customers/memberstatus/activate
This will make your API consistent and easy to use and play with. This is just getting you started though. There is a lot more to see concerning authorisation, request params and queries, and so on. But that’s a story for another time
Design Developers friendly RESTful APIs was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Ikdem Ben Mbarek
Ikdem Ben Mbarek | Sciencx (2021-11-07T19:47:25+00:00) Design Developers friendly RESTful APIs. Retrieved from https://www.scien.cx/2021/11/07/design-developers-friendly-restful-apis/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.