RID Code

Appearance

API Design ​

Overview of how the Backend API is designed, and guidelines for creating new endpoints.

Entity Routing ​

To create a route for accessing, updating, patching or deleting entities, follow this schema (where possible):

http
GET /<entity>/<uid>
http
PUT /<entity>/<uid>
http
PATCH /<entity>/<uid>

The entity name is converted to kebab-case.

For example:

http
GET /assignment-collection/<collectionUid>

Endpoints for lists of entities should follow the same schema as for POST, with the exception that the last entity in the path is plural. If those results aren't specific enough, using query params is favoured over adding new routes.

http
# get all assignment-collections for a user
GET /user/<userUid>/assignment-collections

Creating Entities ​

There are two cases that differ in how routes are defined:

  1. If the entity has a single parent entity, we suffix the entity to the parent entities route.

    For example to create an AssignmentCollection:

    http
    POST /user/<userUid>/assignment-collection

    Because an assignment-collection always as a user that it is assigned to, we put it under the user route.

  2. If the entity has multiple parents, we use the entities name as the root route:

    For example to create an OrganizationUser:

    http
    POST /organization-user

    An OrganizationUser always has an organization and user as parents. Suffixing this would become very awkward: you'd have to choose under which entity you would suffix it, or make a very long route with both the user- and organization uid in the path.

Backend-for-Frontend ​

The /client-area/* routes are special, in the sense that they are always linked to a page in the client-area. This way we can return only data needed for the given page.