I have been working on designing an API that lets client create a product (think of product as something like website domain, something that comes into existence when client makes order for it to the service). Correspondingly with every purchase results in creation of the order object. Which means creation of two resources via a single POST request.

So afaik, the RFC standards recommends sending 201 on resource creation with URI for the resource in the Location header. But in the above scenario, we are creating two resources, domains and orders and I would want response to contain information related to both the resources.

Response would look something similar to this

POST /domains/
 body: {"domain_name": "awesome.com"},

 Body: {"order_id": "1234"}
   Location: http://example.com/awesome.com

But does not look very RESTful. I was wondering if there was a RESTful way to do this?

  • Why do you think this is not RESTful? – Robert Harvey Jun 25 '20 at 13:45
  • Wouldn't modeling it as POST /orders/domains be better? – Andy Jun 25 '20 at 14:11
  • @Andy, imo the parent resource being created is domain and POST /orders/domains makes it seem like domain somehow come under the order resource which does not feel right. Plus the issue of how do I indicate creation of both the resources still remains unsolved with the above endpoint. – Aditya Kumar Gupta Jun 25 '20 at 16:01
  • @RobertHarvey, i cant find specification for similar situation on RFC and seems like a very common case so not very sure if this approcah is RESTful. Moreover the two approaches that I have come across online are mostly either sending Location header or just sending the instance of the complete resource in the response body. So the above approach does not seem very clear and standardised to me and would rather want to avoid it. – Aditya Kumar Gupta Jun 25 '20 at 16:06

REST itself is separate from the HTTP protocol.

A Rest based response should represent the current state of the conversation, or at least the delta of change in the state. This would generally be a description of anything new, and information about things they can now do. Exactly like a web page, which describes information (the content) and has links/forms representing actions the user can take.

The fact that HTTP also suggests that you return the new resource location in a header field location is simply a standardisation, in this case to direct the browser to that content as an automated redirect. So pick the resource that feels best to place here.

HTTP also has a Content-Location which is meant to hold the location of a returned resource.

Putting these two together the software can return location with a url that would naturally redirect to, say the newly created domain. Which works for dumb browsers/agents they will now go to the domain. Smarter agents though can take advantage of the fact that the body contains a resource (the order) and the Content-Location of that order.

However this is missing the point. This is a Representational State Transfer, so nail down the representation. What are you being given and, how are you responding?

Sounds like the user is giving you the domain name. Presumably success means that this is now a thing. It is indeed a resource, but do you need to repeat to the user what they just said?

request> mydomain.com
response> http://mydomain.com

Sure it is legitimate, but what is being achieved here?

What else is happening? The server is making an Order resource. Does the user know about this? Probably not, or at least they don't know where it is.

request> mydomain.com
response> http://example.com/order/abcdef1234567890/

And the order doubtlessly also includes a link to the domain, should they have forgotten what they were requesting.

  • Thanks a lot for the above response. I wanted to return domain related information since after the creation of domain resource there are a bunch of field that client might want to have a look at (expires_at, terminates_at, status etc). The order resource wont contain these fields. – Aditya Kumar Gupta Jun 26 '20 at 13:15
  • 1
    @AdityaKumarGupta, could one of the domain fields be the creation_order with a link to the order resource? Or you could even return the order resource as a sub-resource (with optionally a link to where you can retrieve just the order resource). – Bart van Ingen Schenau Jun 29 '20 at 10:31

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.