This would seem to be a pretty basic question, but I can't seem to find appropraite guidelines for it. What is the "restful" way of POSTing a relationship between two entities that are not necessarily parent/child. As an example, consider customers and orders.

One could create a customer with a POST to /customer. However, what is the best way to create the order? One example would be a POST to /customer/123/order, but what if the order isn't assigned to a customer directly, and could exist on its own (in the case of a web-cart that allows for "anonymous" checkout)? Is the right way, then, to do POST /order?customerId=123

Further, consider the case that an order can be submitted separately from payments (let's say we are invoicing a customer). You could create the order (per either of the methods above), but how would we make the payment? POST /order/123/payment or POST /payment?orderId=123 (if we assume that a payment can be made for something other than an order, and one might want to get information about an order/payment without knowing the specific customer).


I would say that if an order is a first class object, use /order. If it needs to be associated with one or more customers, the customer ids should be an attribute of the order object.

  • But fetching the order would return a full representation of both the order and customer (if one is available, where the customer is a property of the order). It would seem weird to POST an id, but receive back a full representation for an object corresponding to that id. Is that common practice? – Colin M Sep 28 '13 at 0:15
  • Why do you think you would get back both the order and customer? You would get back the order, and one attribute of the order is a customer id or a link to a customer object. – Bryan Oakley Sep 28 '13 at 11:59
  • I'm designing my API such that related entities can be retrieved by specifying a querystring parameter. If you get /order?expand=customer it would return the order entity with the customer entity fully expanded. This seems to be fairly common, and is immensely useful from a client perspective. – Colin M Sep 28 '13 at 12:02
  • @ColinMorelli: That's fine, but so what? The very existence of an expand parameter should be a strong indicator to clients that the "expanded" resource isn't actually part of the main resource and is just related in some way. – Aaronaught Sep 28 '13 at 16:20
  • @Aaronaught I agree, but it doesn't change the fact that the customer property could be either a simple numeric identifier, or a fully-fledged object. That kind of polymorphism seems weird in a REST api – Colin M Sep 29 '13 at 12:28

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.