"Thinking on Service Design (2)" --- translated from "Considerations for Service Design"

avoid accidents

APIs may behave in unpredictable ways due to inappropriate use. Some subtle design decisions often create an avalanche of downstream developers.
To do this the rules shown below should be followed:

Polymorphism (polymorphism) should be avoided, especially in response. In order to avoid unexpected problems when SDk is running dynamically, an endpoint should use a single type.
A single type (homogeneous collection ) should be used, and unless there is a very good reason not to return a heterogeneous collection. If you feel heterogeneous collections are necessary, please discuss the requirements with your API reviewer.
Server-side paging should be supported, even if your resources don't currently require pagination. This prevents you from needing to break the service and then change it when you expand the service.
If the customer scenario really needs to support orderby and the service is confident that it will support this feature permanently, then you can support orderby
Idempotency needs to be met when necessary: GET, PUT, and DELETE in HTTP requests need to be idempotent.

Resilience against modification

When designing your services and APIs, consider a range of scenarios to add flexibility to your clients' implementations. Certain decisions can be made in advance to help software development iterate quickly and avoid service interruptions for upgrades.
There are two suggestions:

Use extensible enum types
Conditional requests (such as ETAG) should be implemented as early as possible to support concurrency.

Behavior manipulation

Most of the operations conform to the standard REST interface, and these operations are one of a series of operations such as Create, Read, Update, Delete, or List (CRUDL).
When a service is able to allow user-specified resource IDs, the recommended practice is to:

Restricts user-specified resource ids to be alphanumeric_-.
Use of special characters not in resource names as actions is differentiated in paths.
Example of resource operation in Azure:
https://.../<resource-collection>/<resource-id>:<action>?<input parameters>
Of course, it is also possible to use other modes. The core factor to be considered is to ensure that the operation information in the path does not collide with the resource id.

Long-Running Operations

Long operation is an API design pattern that is used in scenarios where operations take too long (longer than the client expects to wait for a result). Azure allows this design pattern in two flavors, resource-based long-running operations (RELO) and long-running operations with status monitors.
In both modes, after an API call, the processing of the operation is initiated, and the client will get the result of the operation in subsequent API calls. The following are examples of these patterns:

Resource-based long-running operations (RELO)

In RELO mode, the resource of the operation target contains a status field to indicate whether the current resource has been prepared. After the client initiates the first request, it can subsequently obtain the status of the resource through a standard get request to determine whether the operation has been initialized. The corresponding information flow is as follows: watch

Client sends initialization request to Resource to initialize long-running operation. The initialization operation can be PUT, PATCH, POST or DELETE method.
After the Resource verifies the request, the operation process on the resource is initialized. Resource will send the return value of 200-ok to the client (or 201 to represent the creation operation), and will set the value of status to indicate that the operation on the resource has started.
Client will periodically send GET requests. to determine whether the resource's operation has completed.
Resource restores state information about the resource, and uses non-terminal state values to represent the current state if operations on the resource are still in progress.
If the current resource operation process has been completed, after the Client sends the Get request, the Resource will send a series of indicative values such as Succeeded, Failed, or Canceled to indicate the current result.

Note: This mode is not suitable for scenarios where every request is important to the Client

Long-running operations with status monitor

In LRO mode, the status and results will be populated into the resource status monitor, and the monitor and the target resource are two separate parts.
statmon

Client sends initialization request to Resource to initialize long-running operation. The initialization operation can be PUT, PATCH, POST or DELETE method.
After the Resource verifies the request, the operation process on the resource is initialized. Resource will send the Http status code of 202-Accepted to Client. Additionally, URLs to access status monitors for specific operations are included. The returned Response will also include the minimum waiting time in the Retry-after field.
After waiting for the minimum waiting time, the Client will send a GET request to the status monitor
The status monitor will return the corresponding return value to the client according to the status of the resource.
If the resource processing status is success, failure or cancellation, the corresponding information will be returned to the Client.

LROs will open the corresponding listener for each client, which is a one-to-one mode. LRO is a many-to-one model.

Errors

Another important part of service design is the error returned by http. Errors returned by http messages are a core part of being a developer and an important part of the API you design to interact with others. If your service and the client's service together form a distributed system, errors are inevitable. A well-designed error system can help you avoid costly customer support scenarios. Customers only need to view errors to solve their own problems.
You should design possible errors as much as possible, you can refer to API GuideLines