CODEWITHSUNDEEP
rest
smcg
smcg

Reputation: 3273

Proper way to construct this REST URI?

I want to have a REST resource for Foo and I want to be able to perform a POST to create a new Foo.

Foos can only be of two subtypes - Fizz and Buzz (the models are FooFizz and FooBuzz on the backend and both extend Foo). All Foos are either a Fizz or a Buzz. Most of the other models follow this pattern too (generic with subtypes for Fizz and Buzz). For the short and medium term, there will not be a new type added to Foos. In the long term it's more likely that this application will be obsolete before a new type is added, but the possibility exists.

At any rate, here are some URI schemes I came up with for working with Foos.

  1. POST /foo?type=fizz

  2. POST /foo/fizz

  3. POST /fizz/foo

  4. POST /foo-fizz

  5. POST /foo/{foo-id}/fizz

My thoughts on this:

(1) might be unnecessary client-server coupling since it's dependent on the query string being properly formed. But it makes the most sense to me.

(2) and (3) are undesirable because you want to be able to have the URI go /foo/{foo-id} for performing operations on an individual Foo.

(4) requires Fizzes and Buzzes to become completely separate branches of the URI tree

(5) seems like a decent scheme although it might mess up the URI tree.

Upvotes: 0

Views: 137

Answers (3)

Donal Fellows
Donal Fellows

Reputation: 137567

I'd be strongly tempted to just have a POST to /foo with the type of foo to be created (fizz or buzz) being determined by the contents of the document being POSTed. It would respond with a suitable redirect to the URI for the newly created foo (/foo/{fooId}, presumably) through which you'd manipulate things in the normal way.

Upvotes: 2

D.Shawley
D.Shawley

Reputation: 59563

<soapbox>If you are really doing a RESTful architecture, then you shouldn't need to ask this question</soapbox>.

RESTful architectures include links in the representation that direct the flow of the application. If you are creating a new resource that is a child of a parent resource, then the representation of the parent resource should have an embedded link that tells you what URL and (potentially) which verb to use. Something like:

<link rel="add-child" method="POST" href="http://foo/1234">Add a new child</link>

If you are creating a wholly new root resource then, you probably want to POST to an absolute URL and have either the response document or Location header tell your application where to retrieve a new representation from. The target resource is essentially the "entry point" into your application's state machine.

Upvotes: 0

Justin Pihony
Justin Pihony

Reputation: 67075

Admittedly, I am not a REST expert, however here are my two cents.

Why would you even have a post to foo/{foo-id}? In that case, it would be more of a PUT for an update. The only time you would need to post would be if the id was being auto-created and unknown until actually created. So, in that case, I would lean towards 1 as you are creating a foo and the rest is just information needed to create foo. After that point, would you even need to care about the subtype (fizz or buzz)? I would assume the foo/{foo-id} would be enough information to work on it individually and determine the type from it.

So:

  1. POST /foo?type=fizz **You could possibly even remove the query string and send it in as your creation data, but that is up to you
  2. GET /foo/{foo-id} ...retrieve the created foo
  3. PUT /foo/{foo-id} ...update the created foo
  4. DELETE /foo/{foo-id} ...delete the created foo

That is what I would do at least.

Upvotes: 0

Related Questions