Original link: https://www.ixiqin.com/2023/07/03/apiletter-s1e5-how-to-design-a-batch-operation-openapi-interface-conforms-to-the-restful-style/
Batch create, batch update, batch delete
Now that we’ve finished talking about batch acquisition, let’s talk about batch update. In fact, although there are scenarios for batch update and batch creation, there are not many. operations, but need to use batch resources to implement batch operations.
Taking the user resource (User) as an example, when we need to create, delete, and update it in batches, we need to create a batch resource BulkUser, and create users by operating on BulkUser. Bulk User essentially converts multiple requested resources into asynchronous tasks. After initiation, developers can query specific values in the task results for use.
How to understand asynchronous tasks?
The asynchronous tasks here are more of a design performance, and it is not mandatory to be asynchronous. The asynchronous performance design and related interface implementation are to leave room for vertical expansion in the future. Regardless of whether the behavior is truly asynchronous or not, the task ID & task status needs to be returned in the returned result, so that developers can implement the logic of asynchronous processing by themselves.
{ "code":0, "data":{ "job":{ "id":"123", "status":"ok" }, "results":[ { ... } ] } }
Batch creation
The operation of creating users in batches is similar to the operation of creating a single user. The main difference is that there is a difference in Path, and when passing parameters, attributes of multiple resources will be passed.
Create users in batches
# request POST /bulk_users/ { "users":[ { // user1 ... }, { // user2 ... } ] } # response HTTP/1.1 200 OK { "code":0, "data":[ { // user1 ... }, { // user2 ... } ] }
Bulk update users
When updating in batches, you already know the ID of the resource you need to update, so you can design your interface like this:
#request PUT /bulk_users?id[]=1&id[]=2 { "gender":"other" } # response HTTP/1.1 204 No Content { "code":0, "data":[ { // id=1 ... }, { // id=2 ... } ] }
batch deletion
With the above few examples, it is easier to define batch deletion. like this:
#request DELETE /bulk_users?id[]=1&id[]=2 # response HTTP/1.1 200 OK { "code":0, "data":[ { // id=1 "status":"deleted" }, { // id=2 "status":"deleted" } ] }
Summarize
In the batch operation acquisition scenario, you can consider implementing a more standard search interface through List + Filter or search, and avoid providing customized custom interfaces. From the perspective of specification, both are in compliance with the specification, and both can be provided to users, and they are not mutually exclusive. For creation, update, and deletion that cannot be reused, you can consider using the method of creating asynchronous tasks to implement batch operations, give developers a clear asynchronous expectation, and allow developers to query the implementation of the business by themselves.
This article is transferred from: https://www.ixiqin.com/2023/07/03/apiletter-s1e5-how-to-design-a-batch-operation-openapi-interface-conforms-to-the-restful-style/
This site is only for collection, and the copyright belongs to the original author.