Why does the GitHub API use a PUT request for starring a repository?

Question

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 ?

Answer 1

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.

Answer 2

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.