Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 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 resources of a specific type. A
resource may have one or more collections, with each collection having its own
parent.

### Declarative Clients

Declarative Clients, also known as Infrastructure as Code (IaC), describes a
Expand All @@ -99,10 +105,27 @@ 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 any parent collections. For
example, `/users/`.

### Root Resource

A root resource is a resource for which a collection exists 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
music streaming services may have global shared playlists (e.g. "top
trending"), but may also have playlists nested under a user. In this case, a
playlist is still considered a root resource, since the collection with the
glocal shared playlists has no parents.

### Schema

A schema describes the structure of the request or response of an [API
method](#api-method), or a [resource](#api-resource). It refers both to an
A schema describes the structure of the request or response of an
[API method](#api-method), or a [resource](#api-resource). It refers both to an
OpenAPI schema as well as a protobuf message.

### User
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