Do not design fragile Web APIs

Mathieu fenniak, author of the original article, shouted in his blog: Do not design fragile Web APIs. Otherwise, your partners or third-party developers will hate you and leave you alone. He believes that the key to designing a relatively stable and strong API is to focus on the purpose of the application. The article also shares some precautions for designing excellent APIs. Let's take a look at the following:

If the API is damaged, the customer will hate you.

After the release of many Web APIs, it is like being firmly engraved on the stone and cannot make compatible changes. This is a terrible phenomenon. If you destroy the API, your customers will hate you, and then your boss. Therefore, you must update and maintain the API.

If the API is well designed, it will not be so fragile

Reducing its vulnerability or increasing its toughness is one of the ways to manage API design. The key is to design with the application purpose as the center. That is, in the SOA field, the so-called business-oriented (business-orientation ). This concept may be hard to understand. The following example can explain this point well:

What is the difference between URLs?

http://api.fbi.gov/wanted?order_by=notoriety,desc&limit=10&page=1&fields=name,aka,known_associates,reward,description,last_seen

This is a list from the us fbi. This API contains many functions: You can reserve any domain and sort them in ascending or descending order; you can specify the result count; you can query by PAGE and search by specified details.

Compare the following URL:

http://api.fbi.gov/wanted/most

Although the two URLs share the same destination, they are executed in different ways. The first is designed by a programmer who can provide any function you want. The design does not describe the user's intent, but uses the request definition details to replace.

The intention of the second URL is very obvious, showing the FBI's most wanted criminal list, fuzzy details, which were designed based on the intent.

Designs APIs based on the "intention" to reduce their vulnerability.What are the advantages?

1. Easy to use-no complicated procedures, complicated details, and easy to learn;
2. Flexibility-intention-driven APIs can change with changes on the server side;
3. Consistency-consistency is an essential feature of API design;
4. Loose coupling-this is a backward compatibility problem. You only need to return a fixed value, and the backend compatibility will run well in the intent-driven API;
5. Optimization-when updating the database, it is more difficult to compute and optimize the database than to meet the built-in requirements;
6. Cacheable-Easy to cache. The programmer's design makes the cache difficult (normal queryable parameters) and ineffective (for example, the cache Limit = 5/10/15 is not hit );
7. Easy to develop-the high complexity makes it more difficult and time-consuming to develop and test the programmer's API.
8. Efficient validation model cache--quick check if-None-match/if-modified-since HTTP header and make a "304 not modified" response.

However, I need a more general API design ......

Why do we need generic API design? This is because the intention will allow you to design better APIs. For example, API flexibility. Flexible APIs facilitate the development of user interfaces and allow sorting by field, custom paging, sorting, and filtering or searching.

In addition, with the UI intent in mind, it can also provide a design decision for easy to use, development, flexibility, consistency, loose coupling, optimization, caching, and efficient APIs.

Dry principle (don't repeat yourself)

Do not use the repetition principle during execution, but do not worry about repeated design in API design. If you provide multiple API endpoints to retrieve similar objects based on different intentions, start with common code paths. To provide users with more specific services, You need to constantly maintain the API.

Is this applicable to the real API field?

This is a status API example submitted by GitHub. It marks the repository version through the continuous integration service.

1. Define specific features: specify a country-Revised Version Library
2. GitHub automatically associates the requests and displays them together.
3. There is no HTML or custom country; there are very few data requirements for APIs.
4. Future-oriented: it meets the definition problems in a simple way.
5. Status revision; submit to add more requests.
6. GitHub is flexible and can be changed without compromising compatibility: 1. for the API, GitHub does not support the rewrite function for the whole request function; 2. applicable to other UI fields; 3. if GitHub becomes mercurialhub, subversionhub, perforcehub, cvshub, and rcshub, APIs can also be applied.
7. GitHub allows you to flexibly display the submission status: You can display the status in a mobile application and easily merge localized texts.

There is also a real example of twilio's availablephonenumbers API to search for phone numbers allocated to your account. This looks like a typical API set, however, details and intentions are not highly correlated.

Summary:

To sum up, we will no longer design fragile Web APIs. Here are some points: 1. design APIs based on your own intentions; 2. the details are vague; 3. multiple APIs are provided to differentiate user intentions. 4. share common implementations instead of providing a common service to reduce code duplication.

From: Mathieu. fenniak