APIs

APIs are used to expose application data and interact with the outside world (e.g. web application, mobile clients, ...). Gaudi lets you create REST APIs based on the data models and their relationships. They are designed to offer a predictable behavior with very little code, but which can still be customized and extended when needed.

Using your API definition Gaudi can also automatically generate OpenAPI specification and client integration libraries that help you try, test and integrate your API from day one.

Defining endpoints

API is is a group of operations tha can be performed on a specific resource or model.

Syntax of an API consists of api, entrypoint and endpoint blocks.

The api is a root block that defines an API. It's purpose is to group multiple entrypoints together and allow them to share common configurations.

An entrypoint defines a resource on which we want to perform operations. This resource is typically a data model (e.g. Organization) or one of it's relations. An entrypoint can define one or more operations over specified resource and these operations are described using endpoints.

An endpoint represents a single operation on some resource. Each endpoint corresponds to a single HTTP REST endpoint. Gaudi supports five built-in and one custom endpoint:

• create - uses HTTP POST, creates a new record
• list - uses HTTP GET, returns a list of records
• get - uses HTTP GET, returns a single record
• update - uses HTTP PATCH, updates a single record
• delete - uses HTTP DELETE, deletes a single record
• custom - completely customizable endpoint

Here is a short example of an API specification:

api {
  // operations on "Topic" model
  entrypoint Topic {
    create endpoint {} // POST /api/topic/
    get endpoint {}    // GET /api/topic/{id}/
    custom endpoint {  // POST /api/topic/search/
      POST many "/search"
      ...
    }
    custom endpoint {  // POST /api/topic/{id}/disable/
      POST one "/disable"
      ...
    }
  }
}

Identifying specific records

Each entrypoint is based on a single data model called a "target". Some endpoints operate on a whole collection of targets, while others operate on a single record.

This is reflected in endpoint's context, return type but also in the way a URL is constructed for each endpoint type.

Collection endpoints

Collection endpoints do not refer to a specific record but rather to the whole collection.

Collection endpoint types:

• create endpoint
• list endpoint
• custom endpoint with many cardinality

They require only data model name

/api/topic

Single endpoints

Single endpoints always refer to a specific record and throw error if that record cannot be found.

Single endpoint types:

• get endpoint
• update endpoint
• delete endpoint
• custom endpoint with one cardinality

These endpoints require both data model name and record identifier

/api/topic/{identifier}

In order to look up a specific record, Gaudi expects a record identifier in the URL path. By default, an autogenerated id field is used, but this can be customized using identify:

entrypoint Topic {
  identify { through name }
}

Response schema

Endpoints can return one or more records of target model. To define which part (iow. which properties) of the target model will be returned you can use response block. Response can be specified per entrypoint or per endpoint.

api {
  entrypoint Topic {
    response { id, title, description }
  }
}

Request schema

create and update endpoints typically accept input values from a client, most commonly via HTTP request body. Gaudi analyses the endpoint specification and automatically computes the desired request schema.

tip

Behavior of request schema and working with client data are described in Actions > Accessing client data