0

I was reading this answer, and it says this:

When dealing with a Member URI like: http://example.com/resources/7HOU57Y

...

  • POST: Treats the addressed member as a collection in its own right and creates a new subordinate of it.

...

I've googled for this and found lots of results that say this exact quote, but none of them explain what it means. Can someone elaborate and use examples?

Community
  • 1
  • 1
Daniel Kaplan
  • 62,768
  • 50
  • 234
  • 356

2 Answers2

1

You can use POST to create a resource when you don't know what ID to give it. So you POST it to a resource that acts as a builder of such resources, and the server allocates an ID.

POST to http://example.com/resources and a new resource is created and the server gives it ID 7HOU57Y. You get http://example.com/resources/7HOU57Y.

The new resource is a subordinate of the collection, like a file is to a directory, for example.

But if POST works like this, then POSTing to http://example.com/resources/7HOU57Y should get me a new resource subordinated to this one, like http://example.com/resources/7HOU57Y/XYZ.

This is what I understand from that answer you posted. Of course this is highly dependent on how your service works (e.g. I could specify POST as unsupported for resources like http://example.com/resources/7HOU57Y).

Community
  • 1
  • 1
Bogdan
  • 23,890
  • 3
  • 69
  • 61
  • Interesting. That seems super weird because I'd think it would limit you to one *kind* of subordinate per resource. – Daniel Kaplan Mar 21 '15 at 20:16
  • @DanielKaplan: Not necessarily. As I said in the last paragraph of my answer, this depends on how you build your service: you could decide what *kind* of subordinate to create based on what's inside the request (body, content type, headers, etc). – Bogdan Mar 23 '15 at 18:10
1

Bogdan's answer is correct on what the answer you refer to means, but that answer is a little misleading, because REST is not CRUD with HTTP. POST is not a synonym for Create.

The semantics of the POST method is to do any action that isn't already standardized by the HTTP protocol. POST is the only method that submits the payload to be processed by the targeted resource itself, not by the server. In a way, you can say that with the GET, PUT, PATCH and DELETE methods, the resource isn't aware of what's happening to itself, the server does the whole job, but with POST, the server has to ask the resource to do something.

This means that any action using a POST method must be documented in some way. The clients can assume a GET, PUT, PATCH and DELETE request will follow the RFC 7231, but the final result of a POST will depend on the target media type.

So, if the documentation for the media-type of the resource at http://example.com/resources/7HOU57Y says that a POST will create a subordinate resource and return the URI, fine, that's what it should do. If the documentation says that a POST will launch nuclear missiles against targets in Russia, then that's what it should do. If there's no documentation, someone made a mistake.

Pedro Werneck
  • 40,902
  • 7
  • 64
  • 85