# APIs

An API in Faustine is what Faustine knows about one of your backends: its operations, their request and response schemas, and how it authenticates. Faustine builds it by analyzing your code, a spec or the running service. You manage it in the portal under [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis), and a gateway serves it to AI clients.

## How it works

You create an API by pointing Faustine at the code: a repository, a ZIP, or for GraphQL and gRPC the live service or its schema files. [The analysis](https://docs.faustine.ai/apis/analysis/) reads it and writes the contract into the API's draft. You review the operations, publish a version, add a connection that says where the backend runs, and add the API to a gateway.

An API does not hold a URL or a credential. Those belong to its [connections](https://docs.faustine.ai/apis/connections/), one for each place the backend runs. The same contract therefore serves Staging and Production, and several gateways can serve the same API.

![An API's Overview tab, with what is left to review, its counts and the source of its code.](https://docs.faustine.ai/images/apis/overview-light.png)

## The parts of an API

Each part is a tab of the API page.

| Tab | What it holds |
| --- | --- |
| **Overview** | The setup steps that are still pending, a **To review** list, and the gateways that serve the API. |
| **Operations** | Every call an agent can make, with its kind and whether it requires confirmation. See [Operations](https://docs.faustine.ai/apis/operations/). |
| **Recipes** | Operations that make several calls in one step. See [Recipes](https://docs.faustine.ai/apis/recipes/). |
| **Tests** | Generated suites that call the operations against a connection. See [Generate and run API tests](https://docs.faustine.ai/apis/tests/). |
| **Connections** | Where the backend runs and the credential values Faustine uses. See [Connections](https://docs.faustine.ai/apis/connections/). |
| **Authentication** | How Faustine signs in to the backend, set once for every connection. See [Authentication](https://docs.faustine.ai/apis/authentication/). |
| **Services** | The services a REST API is made of. See [Analyze an API made of several services](https://docs.faustine.ai/apis/several-services/). |
| **Versions** | Every published version and what changed in it. See [Versions and updates](https://docs.faustine.ai/apis/versions/). |
| **Activity** | What Faustine did with the API: analyses, updates, edits and tests. |
| **Settings** | Name, description, code source, analysis notes and deletion. |

## Protocols

Faustine analyzes and serves REST, GraphQL and gRPC APIs. The protocol decides what an operation is and where the contract can come from.

| Protocol | An operation is | The contract comes from |
| --- | --- | --- |
| REST | A route: a method and a path | The code, with an OpenAPI or Swagger file as an optional shortcut |
| GraphQL | A query or a mutation | Introspection of the live endpoint, an SDL or introspection JSON file, or the repository |
| gRPC | A unary method of a service | Server reflection, `.proto` files, or the repository |

## Namespace and operation keys

Every API has a namespace, a short name made of lowercase letters and digits such as `crm`. Every operation has a key under it, such as `crm.deals.create`. Agents call operations by key in every gateway that serves the API.

You choose the namespace when you create the API. It cannot be changed afterwards.

## Draft and versions

The analysis and your own edits go into the API's draft. **Publish** freezes the draft as a numbered version. Gateways serve published versions and never the draft, so an edit reaches agents only after you publish. See [Versions and updates](https://docs.faustine.ai/apis/versions/).

## From an API to an agent

An API serves nothing until three things exist:

1. An analysis that finished. See [Create an API](https://docs.faustine.ai/apis/create-an-api/).
2. A connection. See [Add a connection](https://docs.faustine.ai/apis/add-a-connection/).
3. A gateway that includes the API. See [Add an API to a gateway](https://docs.faustine.ai/agent-gateway/add-an-api/).

The **Overview** tab shows these three steps under **Set up this API** and marks each one when it is done.

## Next steps

- [Analyze your first API](https://docs.faustine.ai/apis/analyze-your-first-api/): go from a repository to tested operations on the example app.
- [Create an API](https://docs.faustine.ai/apis/create-an-api/): the steps of the **New API** wizard for a REST API.
- [The analysis](https://docs.faustine.ai/apis/analysis/): what Faustine reads and what it writes.
- [Operations](https://docs.faustine.ai/apis/operations/): what each operation carries and what you can change.
- [Agent Gateway](https://docs.faustine.ai/agent-gateway/): serve the API to AI clients.