REST and OpenAPI | Faustine Docs

For a REST API, Faustine reads the routes from the service's code and turns each one into an operation an agent can call. An OpenAPI or Swagger document is optional. When you provide one, it fills in what the code leaves out.

Get started

Create the API from APIs > New API with REST as the API type. See Create an API.

Where the contract comes from

The code is the contract. The analysis finds the route files in the repository or ZIP you connect, reads each handler and what it validates its input with, and records one operation per route with its input and output schema.

The Spec (optional) step of the wizard takes an OpenAPI 3 or Swagger 2 document, as .json or .yaml, up to 5 MB. The analysis merges it with what it found in the code:

The code decides which routes exist.
The document fills in descriptions, schemas the code left empty and the deprecated flag.
Routes that appear only in the document are reported as a finding of the analysis and do not become operations.

The code wins where the two disagree, because a document can be out of date.

Operations

Each route becomes one operation with a key under the API's namespace, such as crm.deals.create. The operation keeps its method and its full path with parameters, such as GET /deals/:id, and how the input maps to path parameters, the query string and the body. See Operations.

Connections

A REST connection has a Base URL, such as https://api.nimbuscrm.example. When an agent calls an operation, the gateway fills the path parameters, appends the path to the base URL and sends the query and body.

Credentials

The gateway adds the credential to each request as the API's Authentication tab says:

Strategy	How the credential is sent
API key / static token	An HTTP header or a Query parameter, with an optional prefix.
Bot user	A header, a cookie or a query parameter.
OAuth client	`Authorization: Bearer <access_token>`.
Custom (code)	The headers and query parameters the sign-in function returns.
Pass-through	The caller's `X-Upstream-Authorization` value, as `Authorization`.

See Authentication.

Testing

A connection is tested with a read operation of the API, called through the connection. A REST service has no single endpoint to check before the analysis has found its operations, so the New API wizard does not test a REST connection. Add the connection after the analysis and test it there. See Add a connection.

Next steps

Create an API: the steps of the New API wizard.
The analysis: what the analysis reads and writes.
API frameworks: the frameworks the wizard lists for REST.
Add a connection: give the API its base URL and credentials.