diff --git a/aep/general/0003/aep.md.j2 b/aep/general/0003/aep.md.j2 index 987de638..c1d49720 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 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 @@ -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 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