3 ms·

Help me out, where in the spec does it obligate the API designer to use verbs other than GET and POST?

thunderbong 5y ago
It doesn't. But a lot of the Javascript frameworks follow this and it's considered a de facto standard. Also, most modern SAAS services have APIs that follow this de facto standard.
smt88 5y ago
It doesn't obligate them to use them. It depends on what the API does and how it's designed. My contention is that some common design patterns are violating the HTTP spec by using POST instead of PUT or PATCH. That's fine -- I don't care and don't conform to the HTTP or REST specs myself. My original point is that these distinctions are not some hipster invention, but rather part of the original specs themselves. From the link I posted: > "The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request." The way this plays out in the modern CRUD world is as simple as: POST = "create a new entity" (no ID provided) PUT = "replace an existing entity with this new one" (ID provided for an existing entity) PATCH = "update an existing entity with these new values" (ID provided for an existing entity) The spec is clear that POST, PUT, and PATCH do different things, and it is explicit that they be used as described ("MUST" and "MUST NOT" rather than "SHOULD" and "SHOULD NOT").
- jholman 5y ago
  Agreed about the relevance of the quote you posted. Totally disagree about what it means, in terms of what violates the spec. I do care about conformance with the HTTP specs. REST doesn't even have a spec, so saying you don't conform to the REST specs is... uh... weird. As per your on-point quotation, the semantics of POST are "please handle this". It's the super-vague catch-all, you can use a POST for any "data-accepting process", or things with semantics as general as "a gateway to some other protocol". It's never spec-violating to use POST, POST is the method that makes no commitments. On the other hand, PUT and DELETE have clear semantic limits, and PATCH more-or-less does. As such, there will be situations where PUT and POST are both conformant, situations where PATCH and POST are both conformant, situations where DELETE and POST are both conformant, but no situations where POST is not conformant. > The way this plays out in the modern CRUD world is... Ugh, no. That's the hipster invention. (It's also only modern if you think 2005 is modern, or maybe some earlier date.) The hipster convention is an okay-ish convention, as good as any other cookie-cutter, so I guess if you don't have time to actually pay attention to the implications of the spec I guess you can do worse than teach your juniors to create with POST and update with PUT. But it's not the one way to do it, not the right way to do it, not the only REST-as-in-Fielding-compliant way to do it... it's just the way Rails did it (and maybe some prior framework, I don't know). POST is perfectly okay for updating, modifying, deleting, or anything. POST is analogous to a procedure call... it can do anything. PUT is for setting resources to entities, which yes includes overwriting, but also includes assigning to a previously-unused URL. PUT is analogous to variable assignment in imperative languages like Pascal; it may not modify anything but the resource designated by the request URL. > The spec is clear that POST, PUT, and PATCH do different things, and it is explicit that they be used as described ("MUST" and "MUST NOT" rather than "SHOULD" and "SHOULD NOT"). I, too, think that the spec is pretty clear, but I think you've mis-read it, so maybe it's not so clear. As per my previous question, *where does the spec obligate the conscientious endpoint designer to use PUT?* That is, if you find yourself in a situation where PUT is legal, what bit of the spec says that you MUST NOT use POST instead?

It doesn't. But a lot of the Javascript frameworks follow this and it's considered a de facto standard. Also, most modern SAAS services have APIs that follow this de facto standard.

smt88 5y ago

It doesn't obligate them to use them. It depends on what the API does and how it's designed. My contention is that some common design patterns are violating the HTTP spec by using POST instead of PUT or PATCH. That's fine -- I don't care and don't conform to the HTTP or REST specs myself. My original point is that these distinctions are not some hipster invention, but rather part of the original specs themselves. From the link I posted: > "The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request." The way this plays out in the modern CRUD world is as simple as: POST = "create a new entity" (no ID provided) PUT = "replace an existing entity with this new one" (ID provided for an existing entity) PATCH = "update an existing entity with these new values" (ID provided for an existing entity) The spec is clear that POST, PUT, and PATCH do different things, and it is explicit that they be used as described ("MUST" and "MUST NOT" rather than "SHOULD" and "SHOULD NOT").

jholman 5y ago
Agreed about the relevance of the quote you posted. Totally disagree about what it means, in terms of what violates the spec. I do care about conformance with the HTTP specs. REST doesn't even have a spec, so saying you don't conform to the REST specs is... uh... weird. As per your on-point quotation, the semantics of POST are "please handle this". It's the super-vague catch-all, you can use a POST for any "data-accepting process", or things with semantics as general as "a gateway to some other protocol". It's never spec-violating to use POST, POST is the method that makes no commitments. On the other hand, PUT and DELETE have clear semantic limits, and PATCH more-or-less does. As such, there will be situations where PUT and POST are both conformant, situations where PATCH and POST are both conformant, situations where DELETE and POST are both conformant, but no situations where POST is not conformant. > The way this plays out in the modern CRUD world is... Ugh, no. That's the hipster invention. (It's also only modern if you think 2005 is modern, or maybe some earlier date.) The hipster convention is an okay-ish convention, as good as any other cookie-cutter, so I guess if you don't have time to actually pay attention to the implications of the spec I guess you can do worse than teach your juniors to create with POST and update with PUT. But it's not the one way to do it, not the right way to do it, not the only REST-as-in-Fielding-compliant way to do it... it's just the way Rails did it (and maybe some prior framework, I don't know). POST is perfectly okay for updating, modifying, deleting, or anything. POST is analogous to a procedure call... it can do anything. PUT is for setting resources to entities, which yes includes overwriting, but also includes assigning to a previously-unused URL. PUT is analogous to variable assignment in imperative languages like Pascal; it may not modify anything but the resource designated by the request URL. > The spec is clear that POST, PUT, and PATCH do different things, and it is explicit that they be used as described ("MUST" and "MUST NOT" rather than "SHOULD" and "SHOULD NOT"). I, too, think that the spec is pretty clear, but I think you've mis-read it, so maybe it's not so clear. As per my previous question, *where does the spec obligate the conscientious endpoint designer to use PUT?* That is, if you find yourself in a situation where PUT is legal, what bit of the spec says that you MUST NOT use POST instead?