Web APIs has become a very important topic in the last year. We at WeStartU are working every day with different backend systems and therefore we know about the importance of a good naming convention for APIs.
Essentially, a RESTful API ends up being simply a collection of URIs, HTTP calls to those URIs and some JSON and/or XML representations of resources, many of which will contain relational links.
Each resource has its own address or URI — every interesting piece of information the server can provide is exposed as a resource.
Resource naming is arguably the most debated and most important concept to grasp when creating an understandable, easily leveraged Web service API. When resources are named well, an API is intuitive and easy to use. Done poorly, that same API can feel klutzy and be difficult to use and understand.
RESTful APIs are written for consumers. The name and structure of URIs should convey meaning to those consumers. It’s often difficult to know what the data boundaries should be, but with an understanding of your data, you most-likely are equipped to take a stab and what makes sense to return as a representation to your clients. Design for your clients, not for your data.
URIs should follow a predictable, hierarchical structure to enhance understandability and, therefore, usability: predictable in the sense that they’re consistent, hierarchical in the sense that data has structure — relationships. This is not a REST rule or constraint, but it enhances the API.
Some of the points to consider while writing an API:
- Should be Simple
- Should be Intuitive
- Should always be consistent
- Should avoid camel caps. The norm is to use lower case letters.
- Should use dashes instead of underscores
- While naming an API, consider it to be a folder. Follow the naming pattern similar to the folder structure
- Use Hierarchy
- The most important point to keep in mind while designing an API is maintaining the version number in the API
Should we really add a version number in API URLs?
Maintaining version number in your API is probably an important step while designing the API, but the question arises why do we need? We build the API to return some JSON or XML response so what’s the point in having the version number. Though it might seem useless to maintain the version number but it’s really important. Suppose you are building a system with lots of API’s used by various client. Now at some point in time, we want to modify an API and the response of the API also changes. In that case, instead of changing the API we should prefer use add a new API and keep the old API as it is. This won’t break the client application using the old API as well we have the new API. Later at some point, we can deprecate that API and this will help in the smooth transition from old to new API. The approach is useful but every time maintaining a new set of URI is a difficult task and using a version number is much more helpful.
Example, we can have some API that returns a list of users — v1/users/
Now at some point in time, we modify the API, so instead of maintaining a separate URL, we can just increase the version number — v2/users/
Examples of Naming an API
- v1/users — a list of user
- v1/users/1 — user with an ID of 1
- v1/users/1/organizations — the organizations that user belongs to
- v1/organizations — a list of organizations
- v1/organizations/1 — Organization number 1
- v1/organizations/1/users — The users for that organization
An alternative would be using a query string for filtering:
- v1/users returns a list of all users
- v1/users?organisation=123 returns a list of users that are associated with that organisation