RESTful API Guide? How to design? (Part 1)

Tram Ho

An application that always has beautifully created, standard APIs is probably a great thing for us all, right !!!

Facebook, Google, GitHub, Netflix and a few other tech giants have given developers and products the opportunity to consume their data through APIs and become their platform.

Even if you don’t write APIs for other developers and products, your applications always have very well crafted and handy APIs for us.

There is a lingering debate on the internet about the best ways to design APIs and that is one of the most nuanced. And of course like every other discussion there is no official guide defined for it.

The API is an interface through which many developers interact with data. A well-designed API is always very easy to use and makes the developer life very smooth and fast (Healthy).

The API is a GUI for developers, and if it’s confusing or wordy, developers will start to find alternatives or stop using it. The experience of developers is the most important metric to measure the quality of APIs.

It can be said “API is like a performer on stage and its users are the audience (is us).”

Terminologies (Term)

Important notes regarding the REST API:

  • Resource is an object or representation of something that has some data associated with it and may have a set of methods to operate on it. For example. Animals, schools and staff are resources and deletion, additions and updates are the activities performed on these resources.
  • Collections are a collection of resources, for example, a company is a collection of company resources.
  • The URL (Uniform Resource Locator) is a path through which a Resource can be located and actions can be taken on it.

Endpoint API (Suffix)

I don’t know how to say it properly so look at the following problem:

  • Let the book write a few APIs for companies that have some employees to understand more. / getAllEmprocod is an API that will respond to employee lists. A few more APIs around a company would look like this:
    • / addNewEmployee
    • / updateEmployee
    • / deleteEmployee
    • / deleteAllEmployees
    • / PromoteEmployee
    • / PromoteAllEmployees And there will be tons of other API Endpoint like this for different requests. All of which will contain redundant actions. Therefore, all these API Endpoints will be very heavy to maintain as the number of APIs increases.

What is wrong?

The URL should only contain resources (nouns), not actions or verbs. The API / addNewEmployee path contains the addNew action along with the resource name Employee.

What is the correct way?

API / companies endpoint is a good example that contains no action. But the question is: How do I tell the server about actions taken on the company’s resources and whether to add, delete or update?

This is where the HTTP methods (GET, POST, DELETE, PUT), also known as verbs, play an important role.

The resource must always be in the plural form in the API endpoint and if we want to access resource details, we can always pass the ID in the URL.

  • The GET method / companies will get a list of all companies.
  • Method GET path / companies 34 will receive details of the company 34.
  • The DELETE method / companies 34 34 will delete the company 34. In other cases, if we have resources in a resource, for example, employees of a company, some API endpoints will be:
  • GET / companies / 3 / employees will get a list of all employees from company 3.
  • GET / companies / 3 / employees / 45 get details about employee 45, who belongs to company 3.
  • DELETE / companies / 3 / employees / 45 delete employee 45, person of company 3.
  • POST / companies create a new company and return details of the newly created company.

Is the API more accurate and consistent now?

Conclude

The path must contain the plural resource form and the HTTP method will determine the type of action performed on the resource.

renference: RESTful API Designing Guidelines

Share the news now

Source : Viblo