First, I'd like to explain the meanings of Hierarchical REST API and Normalized REST API that I made up.
- Hierarchical REST API
- Request URL: Can use a hierarchical structure with multiple types of contents. (e.g.
http://www.example.com/customers/12345/orders) - Response body: Can contains all of the requested contents without any omits, including other related data types (e.g. a
customercontains anorder)- e.g.
http://www.example.com/customers/12345
- e.g.
- Request URL: Can use a hierarchical structure with multiple types of contents. (e.g.
{
"name": "John Doe",
"orders": [{
"id": 1,
"price": 10,
"delivered": true
}, {
"id": 2,
"price": 11,
"delivered": false
}
]
}
- Normalized REST API
- Request URL: Hierarchical structure from URL is forbidden.
- NOT OK
http://www.example.com/customers/12345/ordershttp://www.example.com/customers/12345/orders/1http://www.example.com/customers/12345/orders?accepted=true
- OK
http://www.example.com/customershttp://www.example.com/customers?firstName=Johnhttp://www.example.com/customers/12345http://www.example.com/orders/1
- NOT OK
- Response body: Contains all contents of the requested content type. In case of other types are related, only return IDs of it.
- e.g.
http://www.example.com/customers/12345
- e.g.
- Request URL: Hierarchical structure from URL is forbidden.
{
"name": "John Doe",
"orderIds": [1, 2]
}
I think both methods have their own merits and drawbacks
- Hierarchical REST API
- Pros
- Can obtain all required types of content in a single request (e.g. customers, orders, addresses from
http://www.example.com/customers/12345)
- Can obtain all required types of content in a single request (e.g. customers, orders, addresses from
- Cons
- Responses can be exponentially huge and slow if the hierarchy of the data is deep
- Circular reference can happen
- Data duplication (e.g. Results from both
http://www.example.com/customers/12345andhttp://www.example.com/stores/1can contain the sameorderdata)
- Pros
- Normalized REST API
- Pros
- Faster responses (Small payload, no or little joins from data sources, less business logic)
- No data duplication via normalization
- Cons
- Require multiple requests if you need multiple types of content (e.g. to retrieve all
ordersfrom a certaincustomer, at least 2 requests are required from the client)
- Require multiple requests if you need multiple types of content (e.g. to retrieve all
- Pros
My questions are:
- Is there terminology for the
Hierarchical REST APIandNormalized REST API? - Which one is more fit for the REST API guideline? I'm also open to other options.