0

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/
Request 
 body: {"domain_name": "awesome.com"},

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

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

Improve this question
4
  • Why do you think this is not RESTful?
    – Robert Harvey
    Commented Jun 25, 2020 at 13:45
  • Wouldn't modeling it as POST /orders/domains be better?
    – Andy
    Commented Jun 25, 2020 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
    Commented Jun 25, 2020 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
    Commented Jun 25, 2020 at 16:06

1 Answer 1

Reset to default
1

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.

Improve this answer
2
  • 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
    Commented Jun 26, 2020 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
    Commented Jun 29, 2020 at 10:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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