CRUD endpoint architecture

CRUD endpoints is a term that refers to the endpoints that let you GET a collection of a given resource type and that let you GET, POST, PATCH, or DELETE an element of that resource type. The term "CRUD" is an acronym for Create Read Update Delete.

High-level architecture

The following diagram depicts the high-level architecture of a set of CRUD endpoints within Cloud API. These endpoints are for a custom entity whose name is CustomEntity_Ext. (Most of the time, endpoints are generated for custom entities. This is why the examples below feature CustomEntity_Ext. However, it is also possible to generate endpoints for base configuration entities that do not yet have endpoints.)


Diagram of endpoints, resources, and data model entities

There are five CRUD endpoints, but they do not all interact with the same type of resource.

  • The first two CRUD endpoints are for GET (for a collection) and POST. These endpoints interact with a collection resource whose name is customEntitiesExt. (Note that the resource name uses a plural term.)
  • The final three CRUD endpoints are for GET (for a specific element), PATCH, and DELETE. These endpoints interact with an element resource whose name is customEntityExt. (Note that the resource name uses a singular term.
The components of the architecture map to each other in the following ways:
  • The collection resource (customEntitiesExt) makes use of the element resource.
  • The element resource (customEntityExt) maps to the data model entity.
  • The data model entity (CustomEntity_Ext) is used to retrieve data from and send data to the database.

Files that define the architecture

The CRUD endpoint architecture is defined in a series of files, as depicted in the following diagram.


Files that define CRUD endpoint architecture

The swagger file defines the endpoints themselves (the paths, operations, and associated resources).

The schema file defines the schema used by the element and collection resources.

The mapping file defines how information is mapped from the data model entity to the element resource. This information is used for GETs, and for the responses of POSTs and PATCHes.

The updater file defines how information is mapped from the element resource to the data model entity. This information is used for POSTs and PATCHes.

The eti file defines the data model entity.

There are also a series of files that define logic for how the endpoints interact with the application.

  • The apiconfig file is a "glue" file. One of its purposes is to map both the element resource and collection resource to corresponding "Resource" Gosu files. For collection resources, this file can also specify a default sort order.
  • There are two "impl" files that define implementation details.
    • The <collection>Resource.gs file is a Gosu file that defines required behaviors for working with collections. This includes behaviors such as how to retrieve the collection from the database.
    • The <element>Resource.gs file is a Gosu file that defines required behaviors for working with elements. This includes behaviors such as how to initialize a new element.
  • There are two sets of "auth" files that define authorization.
    • There are one or more role.yaml files that define endpoint access for callers of the endpoints.
    • There are a set of access.yaml files that define resource access for callers of the endpoints.