Design a RESTful api for creating a resource and its related resources at once

user_2611007 0
Viewed 1054

I want to know how to design a RESTFUL api for creating a resource and its related resources at once.

For example, I want to create an order which contains a list of items using my RESTFUL API, for example:

{
    order_id:1,
    description: "XXX",
    items: [
        {item_id:1, price:30, ...},
        {item_id:2, price:40, ...}
    ]
}

One way is giving two api

  1. post: api/orders => create a new order and return the order id
  2. post: api/orders/id/items => create related items using the order_id

However, the order and items should be created together. So if the second api failed, it will create an order without any item inside and it is the situation I don't want to see. Actually, I want the backend server to do a transaction and create the order and items at once, it should be succeeded or failed together.

So, is it a good way to put the items in the body of request, and post only once to api/orders ? Or is there other better design for this situation?

Thank you!

orders one-to-many post rest api
2 Answers

Definitely, creating order without items - bad idea. This will ends up with not solid API and not consistent entities. Also, you can't create items using api/orders URI, because this violates the basis of the REST principles.

For your business logic REST API may looks like:

POST api/item
  {
    price: 40,
    name: "xxx",
    ...
  }
<<<<< 201
  {
    id: 1
  }

GET api/item/{id}
<<<<< 200
  {
    id: 4,
    price: 40,
    name: "xxx",
    ...
  }

POST api/order
  {
    description: "xxx",
    items: [
      {id: 1, count: 5},
      {id: 23456, count: 1}
    ]
  }
<<<<< 201
  {
    id: 123442
  }

I think it's unnecessary to put full items in creating order request body. Item ID's will be enough to create order-item bindings on backend.

user_26489420

I want to know how to design a RESTFUL api for creating a resource and its related resources at once.

Perfectly reasonable thing to do. Concentrate your attention on how to describe to the client how to create the appropriate request, and how to interpret the document describing the result.

The clue is in the definition of the 201 Created status code

The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The 201 response payload typically describes and links to the resource(s) created.

(emphasis added)

In the case of the web, the way we would do this is to have a form; the client would provide information in the form and submit it. The browser, following the standard for form processing, would generate a POST (because the semantics are unsafe) request with the form data encoded within the message body and the appropriate content type defined in the header (for instance application/x-www-form-urlencoded).

The response, in term, would be an HTML document with a bunch of links to all of the interesting resources that were created.

Does it have to be HTML? No, of course not - you could use text/plain if it suited your needs. You have somewhat better long term prospects when using a media type that has built into it a notion of links that general purpose components will understand.

user_547340
Related