diff --git a/aep/general/0003/aep.md.j2 b/aep/general/0003/aep.md.j2 index 987de638..fae6498b 100644 --- a/aep/general/0003/aep.md.j2 +++ b/aep/general/0003/aep.md.j2 @@ -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 @@ -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 diff --git a/aep/general/0121/aep.md.j2 b/aep/general/0121/aep.md.j2 index fcf6e0e6..c29a60bd 100644 --- a/aep/general/0121/aep.md.j2 +++ b/aep/general/0121/aep.md.j2 @@ -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