I have a Resource named Company, that can have Post Resource,

I have a path for create of post as: POST /api/company/{companyName}/post.

My question is whether, must i use a path as PUT /api/company/{companyName}/post/{postId} or PUT /api/company/post/{postId} for Update of post resource?

  • I know that i have a bad and probably duplicate question, sorry I can not speak english very good. – ghanbari Nov 3 '15 at 10:06
  • 1
    Upto you, you can define custom routes. – JᴀʏMᴇᴇ Nov 3 '15 at 10:28
  • If you use something like hateos you could return a list of links and maybe the date and title at: /api/companies/{companyName}/posts which would link to: /api/posts/{postId}. The the list of posts for a company is a resource. And the post itself is another resource. – Luc Franken Nov 3 '15 at 13:38

For nested resources like this you will find both options.


would be the more detailed variant. While


is more concise (obviously it requires postId to be unique and the record to have a reference to the companyId).

For Ruby on Rails this type of routes is called shallow nesting and very often used and recommended. Though (at least for Rails) you would in such a case obviously have a third option and omit the company part completely:


unless you need this for anything else inside your code or have different types of posts that are handled differently.

There are not really any clear rules for that scenario (to my best knowledge). A URI only must be able to find a resource. You can even have multiple routes point to the same resource (just make sure you don't duplicate the code to handle them).

I would want to keep things simple, so at least decide for one variant and implement all necessary actions with that route. But it mostly depends on your use case and what makes most sense for the clients of your API.

So if you implement PUT and POST with different routes I would implement both methods on both variants (if there is a chance they will be used at all). So the client can decide if he wants to use /api/company/post/{post_id} or prefers /api/post/{post_id} but does not have to switch between both of them for no obvious reason.

  • thank you, yes postId is unique and post have a reference to company, i can change path to /api/post/{postId}, but i fear that this change break rest rules. have a long path for POST and a short path for PUT, is it matter? – ghanbari Nov 3 '15 at 10:27
  • @ghanbari updated my answer – thorsten müller Nov 3 '15 at 10:49

REST doesn't care what spelling conventions you use for your resource identifiers (so long as they conform to the production rules described in RFC 3986).

In particular, there is no rule that says that, when you create a new resource, it needs to have an identifier with features similar to any other resource identifier.

POST /2ca9f61e-832e-4e47-88dc-6c63a366f70f
201 Created
Location: /5c76d200-c0ed-4f01-aeed-304274c90b4e

That's fine. You can replace either of those UUID with a spelling designed to better serve your human readers, and it's still fine.

You might want the URI to be related for mechanical reasons: resolution of relative references with dot-segments.

/api/company/{companyName}/post/{postId}/../.. =>  /api/company/{companyName}

There are situations where being able to describe an identifier using a relative reference to some base context can be very handy; if you are in one of those situations, you certainly want to choose a URI design that allows you to take advantage of that.

But it isn't required; if balancing trade offs tells you that you are better off with a different design, then do that.


A few thoughts:

Consistency is important, even if only for the "poor humans" who are going to have to understand and work with your API.

• Always avoid designing "two apparently-different ways to get to the same thing."

Beyond that – there really are no "rules." Use your own best professional engineering judgment as to what might work best in this situation.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.