A good interface document, first of all, needs to be clear, so as to eliminate uncertainty and reduce communication costs. This article mainly describes some rules for the author to input interface documents in cross-team cooperation

The service name

XXXSerivce

Interface manager

If readers have doubts, they can communicate with the interface manager

POM coordinates

Most projects use Maven as jar package management tool, we need to provide POM coordinates of SDK, and whether the SDK provided is a release version (official version, stable version being used online) or a Snapshot version (snapshot version, used for testing or joint tuning).

Service description

Describe the functions and implementation principles of the service. It is important to note that:

  1. The interface can be a B port or a C port. It is forbidden to mix BC ports
  2. Whether asynchronous calls can be supported, such as when the interface binds important information to the thread (such as threadLocal), then asynchronous calls cannot be made
  3. . (Expand according to actual situation)

How important

Is it downgradeable? If the interface is not available, will it affect the main process, etc…

If this interface is not invoked, the downstream logic will not be self-consistent, which must be noted

Exception handling

There are two types of exceptions here:

  1. A business exception thrown by the interface itself
  2. The call times out due to network problems

You need to give the upstream caller’s handling method, whether it can be ignored, how to handle the exception, whether it can be retried, and so on. You can give your own handling suggestions

Use the sample

A simple use example can be given if the invocation is more complex

Parameters that

Input parameters: field, type, mandatory, description

Output parameters: field, type, and description

Ability to interface

The current QPS and P99 information of the interface

Monitor the address

If you have a monitoring panel, attach it

The above is the author thinks the interface document needs to have the information, if you have different views, welcome to the comment section, thank you for reading ~