Create an API | Faustine Docs

The New API wizard creates an API and starts its analysis. This page covers a REST API that is one service. For other cases, see Create a GraphQL API, Create a gRPC API and Analyze an API made of several services.

Before you begin

A model provider connected to your workspace. The analysis runs on it. See Connect your model provider.
The backend's code, in a GitHub, GitLab or Bitbucket repository that Faustine can read, or as a ZIP. See Connect GitHub.

Describe the API

To start the wizard:

In the portal, go to APIs and select New API.
In API type, select REST. If you do not know the protocol, select Not sure and the analysis detects it.
In Architecture, select One service, then Continue. A backend-for-frontend that declares its own routes is one service.
In Language & framework, select your framework, or Other / not listed. The choice is a hint for the analysis.
In Details, enter a Name and a Namespace, then select Continue.

The namespace starts every operation key, as in billing.invoices.list. It accepts lowercase letters and digits, and it cannot be changed after the API is created. The wizard reports a namespace that another API of your workspace already uses.

Connect your code

In Connect your code, choose where the code comes from.

Select the provider: GitHub, GitLab or Bitbucket.
Select the connection, then the Repository and the Branch. All three are required.
If the API lives in a folder of a monorepo, enter the folder in API path.

Select Upload a ZIP.
Drop the archive, or choose it. Zip the source without node_modules, .git or build output. A ZIP can be up to 500 MB.
If the API lives in a folder of the archive, select it in Folder to analyze.
To keep the code after the analysis, turn on Keep the code after the analysis.

Faustine deletes the archive when the analysis finishes unless Keep the code after the analysis is on. Without the stored code you cannot re-analyze the API or open the Advanced editor until you upload it again.

Anything we should know about this API? is optional. The analysis reads it before it reads the code, so use it for vocabulary, routes to skip and unusual error handling. Select Continue.

Add a spec and choose how the API updates

In Spec (optional), upload an OpenAPI or Swagger file (.json or .yaml, up to 5 MB), or select Skip. With a spec, the analysis takes routes and schemas from it and reads the code for rules and authentication.
In Keep the API up to date, select Automatic or Manual, then Continue. This step appears only when the code comes from a repository. See Keep the API up to date.
In Review & analyze, check the summary and select Create & start analysis.

The portal opens the analysis page, where the run shows its stages and its log. You can leave the page while it runs. When the run finishes, select Open the API page.

Troubleshooting

Symptom	Cause	Fix
`The namespace "…" is already used by another API.`	Namespaces are unique in a workspace.	Enter another namespace in Details.
`The file is larger than 5 MB.`	The spec file is over the limit.	Upload a smaller spec, or skip the step and let the analysis read the code.
Keep the API up to date does not appear	The code is a ZIP, which has no branch to watch.	Update the API with Upload a new version in the Actions menu.

Next steps

The analysis: what the run does and how to read its result.
Review and test an operation: check what the analysis found.
Add a connection: tell Faustine where the backend runs.
Add an API to a gateway: serve the operations to AI clients.