# REST and OpenAPI

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**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) > **New API** with **REST** as the **API type**. See [Create an API](https://docs.faustine.ai/apis/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](https://docs.faustine.ai/apis/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](https://docs.faustine.ai/apis/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](https://docs.faustine.ai/apis/add-a-connection/).

## Next steps

- [Create an API](https://docs.faustine.ai/apis/create-an-api/): the steps of the **New API** wizard.
- [The analysis](https://docs.faustine.ai/apis/analysis/): what the analysis reads and writes.
- [API frameworks](https://docs.faustine.ai/technologies/api-frameworks/): the frameworks the wizard lists for REST.
- [Add a connection](https://docs.faustine.ai/apis/add-a-connection/): give the API its base URL and credentials.