Bulk Create and Update in REST API: Handling Resource Associations in a Single Request

Introduction and Problem Context

In modern web application development, efficiently handling resource associations and bulk operations is a common requirement. This article uses the association between documents (Doc) and binders (Binder) as a case study to explore how to design a REST API that supports bulk creation or update of documents and their assignment to binders in a single request. Key challenges include HTTP method selection, URI design, response handling, and operation atomicity, which directly impact API usability and adherence to REST principles.

HTTP Method Selection: Comparing POST and PATCH

For bulk operations, POST and PATCH are the primary candidate methods. The POST method is typically used to add elements to a list resource, but its flexibility allows support for various actions, including bulk processing. For example, sending a POST request to the /docs endpoint can include an array of documents to create or update resources simultaneously, without explicitly describing each operation. A code example is as follows:

[
    { "doc_number": 1, "binder": 4, "title": "Report" },
    { "doc_number": 2, "binder": 4, "title": "Plan" },
    { "doc_number": 3, "binder": 5, "title": "Summary" }
]

In contrast, the PATCH method is designed for partial resource modifications and requires defining an update format (e.g., JSON Patch). While more semantically precise, it may add complexity in bulk scenarios. The PUT method is suitable for complete replacement of resource collections and is not ideal for mixed create-and-update operations.

URI Design: Strategies for Resource Paths vs. Sub-Resource Paths

URI design should clearly reflect resource relationships. One approach is to use the resource path for the document list (e.g., /docs), including binder association information in the request body. Another approach is to adopt a sub-resource path of the binder (e.g., /binder/{binderId}/docs), simplifying the request body by implicitly handling associations. For example, sending a POST request to /binder/1/docs can automatically associate documents with binder ID 1. A code example is as follows:

[
    { "doc_number": 1, "title": "Report" },
    { "doc_number": 2, "title": "Plan" }
]

The advantage of sub-resource paths is reduced redundancy in the request body, but it may limit cross-binder bulk operations.

Response Handling and Error Management: Status Codes and Atomicity Considerations

Responses for bulk operations must consider global status and granular results. For atomic operations, return 200 OK on success and status codes like 400 Bad Request on failure, ensuring all operations either succeed entirely or roll back. Non-atomic operations allow partial success, returning 200 OK with detailed results for each operation in the response body, similar to implementations like Elasticsearch's bulk API. Asynchronous processing can use 202 Accepted, with clients polling for results.

Supplementary Solutions and Best Practice References

Other answers provide valuable supplements. For instance, using the 207 Multi-Status response code supports non-atomic operations, including each sub-request's status in the response body. Batch request endpoints (e.g., /batch) allow encapsulating multiple independent requests, enhancing flexibility but potentially deviating from REST's resource-oriented principles. The navigation links feature in the OData specification is also worth referencing for handling entity relationships.

Conclusion and Implementation Recommendations

When designing bulk create-and-update APIs, it is recommended to prioritize the POST method combined with resource or sub-resource paths, choosing atomicity or non-atomicity based on business needs. Responses should provide clear status information, and error handling must balance user experience with system consistency. By adhering to REST principles and HTTP standards, efficient and maintainable APIs can be built to support complex resource association scenarios.