Hierarchical REST API vs Normalized REST API

Question

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 customer contains an order)
    • e.g. http://www.example.com/customers/12345

{
  "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/orders
      • http://www.example.com/customers/12345/orders/1
      • http://www.example.com/customers/12345/orders?accepted=true
    • OK
      • http://www.example.com/customers
      • http://www.example.com/customers?firstName=John
      • http://www.example.com/customers/12345
      • http://www.example.com/orders/1
  • 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

{
  "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)
  • 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/12345 and http://www.example.com/stores/1 can contain the same order data)
• 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 orders from a certain customer, at least 2 requests are required from the client)

My questions are:

• Is there terminology for the Hierarchical REST API and Normalized REST API?
• Which one is more fit for the REST API guideline? I'm also open to other options.

Answer 1

Is there terminology for the Hierarchical REST API and Normalized REST API?

No.

Which one is more fit to the REST API guideline?

They are both "fine".

Consider the world wide web, and how we deliver CSS instructions to the browser. Can we embed CSS directly into an HTML page? Yes. Can we link to CSS that is fetched via a different resource? Yes.

Do both approaches "fit to the REST API guideline". Yes - more precisely, they work because HTML is a general-purpose standardized media type, with rules about how references to CSS work; and those rules are understood by everyone the same way.