In the past, when developing or updating an API, we often had to discuss the structure, naming, and functionality of the API in depth, which took a lot of time.

As the API industry is booming, API design is becoming more and more important. Over the years, rules such as REST apis have become widely accepted and can be applied to the development process to help teams quickly reach consensus and improve performance.

The principles and rules of API design will be introduced next. In this article, we’ll focus on the Web API.

An API is a combination of Application, Programming and Interface. It connects two applications through a written Interface that can be used internally or externally.

Basically, every time we use a Web application, send a message, or access a URL, we’re using the corresponding API, whether it’s a client application or a server application, to pass data through the API.

Because all communication between the API and everything else is done over HTTP, HTTP is important enough to require different request methods for different purposes and requirements:

  • GET – Requests a representation of a specified resource. Requests using GET should only retrieve data.

  • POST – Submits data to the specified resource.

  • PUT – Replaces all current representations of the target resource with request data.

  • DELETE – Deletes the specified resource.

  • PATCH – Applies partial changes to the resource.

Specific usage can be understood in the public number of other articles, there are also a lot of related content on the Internet, but more.

Development techniques are evolving, and API architectures and protocols are growing. Different architectures and protocols have different data types, command modes, and functions. The most popular protocol was XML-based, but JSON is gradually replacing it.

The most common API architecture in the world today is undoubtedly REST. When we use the REST API, we must follow the JSON specification and issue test requests in a valid JSON format. Good apis usually follow these rules:

  • The API must be separate from the back end, data store, client, and so on. For security and flexibility, the API must be a separate hierarchy;

  • Different requests should be handled independently of each other. This also means that each request needs to contain all the information needed to process it;

  • The API should send requests independently of the client and work the same way. For example, on a Web server, load balancer, or any other client;

  • Resources should be cacheable on the client or server side. This improves performance on the client side and scalability on the server side;

  • Handle the error and return the appropriate error code. Help users know if it’s 404 or something else;

  • The API must be error tolerant. Users sometimes send repeated requests due to physical reasons, such as network timeout, etc. Such requests should return the same result.

  • Use Eolink or another tool to generate API documentation for the specification. API documentation is required for both use and work handover.

There are also some nice ways to name endpoints:

  • Use only nouns: Endpoints should be named with nouns that specify the content of the resource, rather than adding verbs for the functionality being performed. For example, name endpoint/Users and use different HTTP methods to handle user entities rather than creating multiple endpoints like /get-user, / Add-user, etc.

  • Use clear names: The names of endpoints should be clear and intuitive. Do not use any shortcuts or abbreviations unless it is clear that – / IDS is understandable and preferable to/ipids-numbers;

  • Build hierarchies with forward slashes: Group endpoints into logical groups. As /departments/ IDS and /departments/managers, are better than /departments- IDS and /departments-managers;

  • Use lowercase only: urls are case sensitive, so it’s best to avoid using uppercase whenever possible;

  • Use “-” to separate words: Different words in endpoint names are usually separated by “-” instead of underscores or camel spellings;

  • Avoid special characters: urls can only be sent and received using the ASCII character set, so only characters from that character set can be used. At the same time, other such as “%”, “[]”, “{}”, “|”, “, “” < >” also had better avoid to use.

Most REST apis are produced in conjunction with the microservices architecture.

In this case, this API structure will provide the flexibility to change the underlying logic, add or remove components, and so on, without changing other communication protocols with other services.

Now that you have some knowledge of Web API design, it is a reasonable and excellent solution that has been proven by countless people. Try it out and put it to work!

The interface management tool used in the figure is eolink. If you are interested, you can use www.eolink.com