Skip to content

Commit

Permalink
feat(3): add terminology for root resources and collections
Browse files Browse the repository at this point in the history
We are missing a term to describe a resource whose collection has
no parents. Since this is helpful for things like building a navigation
tree, define the term.
  • Loading branch information
toumorokoshi committed Jan 21, 2025
1 parent 8e34b04 commit dfb3485
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 3 deletions.
22 changes: 22 additions & 0 deletions aep/general/0003/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@ addresses.
Either a programmatic client or a user that consumes an API. This term should
be used when a statement refers broadly to both programs and users.

### Collection

A collection represents a discrete set of a specific resource type. A resource
may have one or more collections, with each collection having it's own set of
parent collections.

### Declarative Clients

Declarative Clients, also known as Infrastructure as Code (IaC), describes a
Expand All @@ -99,6 +105,22 @@ Examples of complexities that declarative clients abstract away include:

[Terraform][] is an example of such a client.

### Root collection

A [collection](#collection) that does not have a parent collection. For example,
`/users/`.

### Root Resource

A `root` resource is a resource which has a collection that has no parents. In
other words, it is a resource that has a collection that appears at the root of
a resource hierarchy.

A root resource may also appear as a child of another resource: for example, a
user permission may exist globally, but also as a child of a individual object.
In this case, the resource is still considered a "root" resource, because at
least one collection does not have a parent.

### Schema

A schema describes the structure of the request or response of an [API
Expand Down
7 changes: 4 additions & 3 deletions aep/general/0121/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ When designing an API, consider the following:
A resource-oriented API **must** be modeled as a resource hierarchy, where each
node is either a simple resource or a collection of resources.

A _collection_ contains resources of _the same type_. For example, a publisher
has the collection of books that it publishes. A resource usually has fields,
and resources may have any number of sub-resources (usually collections).
A [_collection_](./0003#collection) contains resources of _the same type_. For
example, a publisher has the collection of books that it publishes. A resource
usually has fields, and resources may have any number of sub-resources (usually
collections).

**Note:** While there is some conceptual alignment between storage systems and
APIs, a service with a resource-oriented API is not necessarily a database, and
Expand Down

0 comments on commit dfb3485

Please sign in to comment.