0

I am developing my own REST API and was looking for other well-established APIs to see what they do when they have a need to expose some sort of action that can be made on a resource. One that came up was the ability to star and unstar a repository/gist on GitHub. According to their docs, you can star with PUT /gists/{gist_id}/star, and unstar with DELETE /gists/{gist_id}/star.

This is what the docs say about the HTTP verbs:

PUT     Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE  Used for deleting resources.

Delete makes sense to me, but why would PUT be used? Since you can GET /gists/{gist_id}/star it seems "star" is some sort of functional resource. So I guess I'm just wondering why PUT instead of POST?

Timothy Fisher
  • 1,001
  • 10
  • 27
  • Unless one of the actual Github-Devs will answer this question, answers are only speculations and therefore reflect just opinions. Such a question is unfortunately not in scope with SO agenda. I therefore voted to close this as opinionated. Feel free to reformulate your question so that it won't ask for opinionated views. – Roman Vottner Aug 20 '20 at 01:26
  • No problem. I actually found somewhat of an answer in a comment on the software engineering stack exchange. The answer references the same article I read that brought me here and it's basically the same question. Still seems there's a lot of opinions about it still. Answer is here with specific mention to Raphael's comment: https://softwareengineering.stackexchange.com/a/270421. I think it's the same as what Jim Webber said in the video that you linked in the below comment. – Timothy Fisher Aug 20 '20 at 01:37

2 Answers2

2

So I guess I'm just wondering why PUT instead of POST?

PUT, in HTTP, has somewhat tighter constraints on its semantics than POST does -- for instance, the semantics of PUT are idempotent, which is a convenient thing to know when you are sending requests over an unreliable network; PUT tells you that there won't be a problem if the server receives more than one copy of the request message.

(This is a lot like asking about why GET instead of POST, except that the differences are smaller)

Which is why when you have a simple remote authoring use case, like uploading a document to a document store, that PUT is the superior choice -- because it allows general purpose clients (like browsers) to do useful things without needing extra out of band information.

https://docs.github.com/en/rest/overview/resources-in-the-rest-api#http-verbs does NOT define the semantics of the HTTP methods. The standardized definitions of GET, PUT, POST and so on are in RFC 7231.

If you review the RFC, you'll discover that the semantics of HTTP PUT also cover "create":

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

"Make your copy of this document look like my copy" is a perfectly reasonable way to communicate information to the server, and the meaning of that message doesn't really depend at all on whether or not the server already knows about the document when the request is processed.

I am developing my own REST API

Do make sure you review Jim Webber's 2011 talk, which I think goes a long way toward clarifying how web based API are "supposed" to work.

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
1

One reason I could see is that the star “exists”, and these routes are just toggling some sort of “active” property on the star. So you wouldn’t use POST because you’re not creating the star, just toggling its active property.

Edit: this is also just a guess based on how I’d implement something like this, as their docs are kind of sparse.

foscjos
  • 37
  • 6
  • 1
    No, for some reason plenty of people confuse POST with a create method and PUT with an update method. Don't get me wrong, it can be used that way, but the methods have more meaning to it than just this oversimplification. Probably the actual purpose why they used PUT is, as [Jim Webber put it](https://www.youtube.com/watch?v=aQVSzMV8DWc&t=19m40s), that PUT is idempotent whereas POST isn't, and it should be used for absolute state changes or anything monetary related. I highly recommend to watch his whole talk – Roman Vottner Aug 20 '20 at 01:20
  • Thanks for the info, I’ll check out that link. – foscjos Aug 20 '20 at 01:42