Badly designed API infrastructure causes many issues, such as
The inability to scale or modify the APIs in production.
Exposing confidential parameters in the URL path.
Improper naming convention, which leads to confusion.
Drag in developer cooperation due to confusions & misunderstanding.
Multiple APIs for accessing the same type of resources.
Lack of API monitoring tools to analyze and visualize API usage, status, etc.
Therefore, I think it's important to invest time in learning and following some standards and finding some tools for building and analyzing RESTful APIs. We can't build good, efficient APIs that meet all standards in one day because it's a long-term process that requires a lot of iterations. Here, I will explain a few standards and rules that everyone can follow to build better RESTful APIs. Consider this article as a starting point for building efficient, maintainable, and scalable APIs.
Small Mistakes that Cost a Lot
Some problems and mistakes that we are going to discuss here may seem insignificant, but as the product grows or as the customer base increases, these minor mistakes can cause significant headaches. Addressing these issues, especially without disturbing multiple client applications or causing problems for end users, is the most challenging aspect.
Better Structure, No Confusion
In the long term, having a solid resource naming strategy is a great investment in API design. As features expand, maintaining a proper naming convention helps to avoid confusion in the future and improves readability.
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g., a person), and so on. -Architectural Styles and the Design of Network-based Software Architectures by Roy Fielding
Resource Relationship
The fundamental purpose of an API is to provide access to appropriate resources for the user. But what exactly is a resource?
For example, on a blogging platform such as Ghost Blogging Platform, let's check how the APIs are designed. The main resources on ghost blogging platform includes posts, authors, pages, etc. Each post typically has different attributes, such as:
id: unique identifier for the blog.
author: Author of the blog.
createdAt and updatedAt: Timestamps indicate when the post was created and last updated.
A resource can be in the form of a singleton (a single blog) or a collection (a group of blogs by an author). There is a standard naming convention for singletons and collection resources:
GET /content/posts/ is a collection resource. GET /content/posts/{id}/ is a singleton resource.
Nouns in URLs
REST-styled APIs are primarily for collecting resources and establishing communication, not for performing actions or operations. Consider these examples:
Preferred Approach:
GET /content/pages/GET /content/authors/
Less Preferred Approach:
GET /content/get-blogsGET /fetch-authors
The first set is clearer and more straightforward. Since it's a GET method, there's no need to explicitly mention get-blogs unless it's a RPC-styled method.
Read the full article here: https://journal.hexmos.com/designing-rest-api-techniques/#security