Nested resources

Describe hierarchical relationships between resources with subpaths.

Most APIs provide functionality in the form of multiple resources that coorperate with each other. These resources are often related to each other in a heirarchy. For example, in a banking API each Customer resource may have one or more Account resources, where each account belongs to a single customer.

It can be helpful to developers to communicate such parent-child relationships using nested URI paths. For example, the customers and accounts example could be modelled with the following URIs:

Guidelines

Nest resources that have clear parent-child relationships

Indications that you should nest a resource within another include:

• The child resource is exclusively scoped to its parent in a has-a or belongs-to relationship.
• Retrieve and list operations on the child resource are always scoped to the parent.
• Deleting the parent resource should also delete all child resoures in cascade.

On the other hand, signs to avoid nesting resourcs include:

• It is a valid use case to list all entities of a given type across all parents. For example, listing all accounts owned by any customer in an Admin dashboard.

Sometimes the right approach is to provide both a top-level collection resource and a collection resource scoped to a parent. The two collections probably serve different use cases, for example an admin persona use case versus a user persona use case, and might involve different authorizations, parameters or representations.

Make path parameters descriptive and unique

With a flat URI structure, path parameters identifying objects are often simply named id.

Nesting resources introduces URIs with more than one path paremeter, so id is no longer unambigous.

Even if your URI structure starts out flat, name all path parameters after the object they identify. This way, of you add nested resources later, your parameters will be consistently named.

Prefer this:

/customers/{customer_id}
/customers/{customer_id}/accounts/{account_id}

Avoid this:

/customers/{id}
/customers/{id}/accounts/{account_id}

Examples

Here are some examples of public APIs and the URL structures they employ:

Twitter API: Uses a resource-based URL structure to represent tweets, users, and relationships. For example, /users/{user_id}/tweets/{tweet_id}.

GitHub API: Adopts a resource-based URL structure to represent repositories, issues, and pull requests. For instance, /repos/{owner}/{repo}/issues/{issue_number}.

OpenAPI definitions

Tips for well-structured OpenAPI definitions:

• Describe each resources with a Tag object.
• Associate each operation with a tag.
• Use the same tag for related collection and object resources.
• Spell tag names as plural phrases. Autogenerated documentation creates section headings from tag names.
• Associate nested resources with distinct tags to the parent resource.

Here is an example OpenAPI document:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Nested Resources Example API",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Customers"
    },
    {
      "name": "Accounts"
    }
  ],
  "paths": {
    "/customers": {
      "tags": ["Customers"]
    },
    "/customers/{customer}": {
      "tags": ["Customers"]
    },
    "/customers/{customer}/accounts": {
      "tags": ["Accounts"]
    },
    "/customers/{customer}/accounts/{account}": {
      "tags": ["Accounts"]
    }
  }
}