I am writing a YAML document using swagger to design a RESTful API method for cloning a resource. I have a few options and don't know which would be best. Please can someone advise?
Options:
Thanks for any help!
If you want to COPY a resource, then, yes, COPY is an obvious choice.
(and yes, it would be good to pull the definitions of COPY and MOVE out of RFC 4918 to untangle them from WebDAV).
Most of these options are perfectly good choices. A lot of it just your style choice in the end. Here are my comments on each of your options.
Relinquishing the responsibility of cloning the resource object to the consumer
In general I don't really have a problem with this solution. This option is very straight forward for a user to understand and implement. It might be better than coming up with some proprietary cloning functionality that your users have to learn how to use.
Using the WebDAV HTTP extensions which provides a COPY method
I like to stick to the standard methods as well. I would not use COPY
, but I wouldn't appalled if you did.
POSTing to /{resource}?resourceIdToClone={id}
This is a perfectly good solution. From a REST standpoint, you don't really have a conflict with the rest of your API. The URI with a query parameter identifies a different resource than the URI without the query parameter. Query parameters are a URI feature for identifying resources that you can not be referenced hierarchically. However, it might be difficult to separate these in your code because of the way most REST frameworks work. You could do something similar to this except with a hierarchical URI such as /{resource}/clone
. You could POST to this URI and pass the resource_source_id
in the body.
Adding a new resource called 'CloneableResource' and performing a POST to /CloneableResource/{resource_type}/{resource_source_id}
There is nothing wrong with this approach from a REST standpoint, but I think adding a new type is both unnecessary and clutters the API. However, I disagree with your intuition there could be problem with having a resource that has only a POST operation. It happens. In the real world, not everything fits nicely into GET, PUT, or DELETE.
A GET against /resource/{id}?method=clone
This is the only option of the 5 that I can not condone. It seems from your description that you already understand why this is a bad idea, so I'm not sure why you are considering it. However, all you have to do to make this a good solution is to change GET to POST. It then becomes very similar to the #3 solution. The URI could also be hierarchical instead of using a query parameter. POST /resource/{id}/clone
would work just as well.
I hope this was helpful. Good luck with your decision.
Influenced by project requirements and the range of preferences amongst members in my team, option 1 will serve us best at this stage.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With