search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.91k stars 9.07k forks source link

Create vs update, PUT / POST / PATCH, and minimal OpenAPI redundancy #1453

Closed mewalig closed 8 months ago

mewalig commented 6 years ago

Suppose I have a service that must provide separate "create" vs "update" operations for creating a new resource. The calls for create and update with be exactly the same except for whatever differentiates between create and update. That differentiation could come from the method (post vs put vs patch), from the url (/resource/id/create vs /resource/id/update), from the data in the body-- it seems that request method is the only one I have seen recommended, but whatever the case may be, everything about the create/update request would otherwise be the same.

  1. If I decided to implement this using two different methods (e.g. PUT vs PATCH), is there a way using OpenAPI to not have to repeat the duplicate parts of the specification?
  2. If the answer to the above is that, there is no way, then, is request method (PUT vs PATCH) the only approach for handling this scenario that would be considered "well-designed", or could any of the other approaches (using URL or data to differentiate create vs update) work equally well while also eliminating that redundancy in the corresponding OpenAPI spec?
hkosova commented 6 years ago

Related: Vary presence and requirement of properties with CRUD operation

antillean commented 6 years ago

The "Reusable Bodies" section in the documentation on Describing Request Body mostly solves this problem. The example there shows how you can use it to eliminate the duplication in the specifications for POST and PUT requests to the same resource type.

kscheirer commented 2 years ago

I am evaluating this as a possible use case for overlays, https://github.com/OAI/Overlay-Specification/discussions/9.

I do not think overlays would be much help here. Previous comment shows to to handle this case in openapi3.

handrews commented 8 months ago

This was partially answered a while ago. For the rest, as with the similar issue #2201, the magnitude of change means it will be addressed in Moonwalk (OAS 4) rather than 3.x. Please join the discussions in that repo, such as OAI/sig-moonwalk#30 (resource oriented).