Analyze your first API

At the end of this tutorial, Faustine has a list of the operations of the Nimbus CRM backend that you have reviewed, and one of them has returned real data from your running server.

Nimbus CRM is the example app of these docs: a CRM with contacts, companies, deals, tasks and invoices. Its backend is an Express app with a REST API under /api. The code is at github.com/faustine-ai/example-nimbus-crm.

In this tutorial, you:

• Create the API
• Run the analysis
• Review the operations
• Add a connection
• Test an operation

Before you begin

• A model provider connected to your workspace. See Connect your model provider.
• A fork of faustine-ai/example-nimbus-crm in a GitHub account that Faustine can read. See Connect GitHub.
• Nimbus CRM running at a URL that Faustine can reach over the internet. A server on localhost is not reachable. The repository's app/README.md has the command for the single-container build, which serves the API on port 4000.

Create the API

1. In the portal, go to APIs and select New API.
2. In API type, select REST.
3. In Architecture, select One service, then Continue.
4. In Language & framework, select Express.
5. In Details, enter Nimbus CRM in Name. The wizard fills Namespace with nimbuscrm. Select Continue.
6. In Connect your code, select GitHub, then your fork in Repository. Select main in Branch.
7. In API path, enter app/backend. The repository also contains the front end, and the API is in this folder.
8. Select Continue.
9. In Spec (optional), select Skip. Nimbus CRM has no OpenAPI file, so the analysis reads the routes from the code.
10. In Keep the API up to date, leave Automatic selected and select Continue.
11. In Review & analyze, select Create & start analysis.

The namespace is the first part of every operation key, such as nimbuscrm.contacts.list. It cannot be changed later.

Run the analysis

The portal opens the analysis page. The run clones the repository, discovers the operations and how a client authenticates, and proposes a kind and a confirmation flag for each operation. You can leave the page while it runs.

Select Open the API page.

Review the operations

The Overview tab shows Set up this API with three steps. Analyze the API is done. Add a connection and Serve it from a gateway are pending.

1. Select the Operations tab. The operations are grouped by resource: /contacts, /companies, /deals and the others.
2. Select the row of the operation that lists contacts. It unfolds to show its Endpoint, GET /api/contacts, its kind and its description.
3. Select Schema in the same row. The Request tab shows the input the operation accepts. Close the dialog.
4. Check the Kind column of the group. Operations that create, update or delete are write. To change a kind, select the pencil next to its badge.
5. Check the Requires confirmation column. Turn the switch on for each delete operation where it is off.
6. If you changed anything, select Save changes.
7. Under the table, open Hidden (auth endpoints). The login route is listed there. Faustine uses it to sign in and does not expose it to agents.

Go back to the Overview tab. If To review has a row about operations that require confirmation, select Looks right.

Add a connection

A connection tells Faustine where the backend runs and which credential to use. This tutorial covers the minimum. For every field, see Add a connection.

1. Select the Connections tab, then New connection.
2. In Endpoint, enter Staging in Name. In Base URL, enter the origin of your server, such as https://nimbus.example.com, without /api. The operation paths already start with /api.
3. In Credentials, enter the values the step asks for. They depend on the sign-in in the API's Authentication tab. For a sign-in through the login route, enter the seeded account from the Nimbus CRM README: [email protected] and admin123.
4. Skip Labels.
5. In Test, select the operation that lists contacts in Operation, then run the test.
6. In Review & create, select Create connection.

If the Credentials step reports that the sign-in is not set, open the Authentication tab first. See Authentication.

Test an operation

1. Select the Operations tab.
2. In the row of the operation that lists contacts, select Test.
3. In Connection, select Staging.
4. Replace the content of Input with {}. The operation has no required input, and its optional search and status fields filter the list.
5. Select Run test, then confirm with Run test.

Repeat the test for the other read operations you plan to serve. A test of a write operation creates or changes records on your server.

What you built

Your workspace has an API named Nimbus CRM with reviewed operations and a connection to your server. It is listed under APIs, and it updates when you push to the fork.

Next steps

• Write your first recipe: add an operation that creates a company and its first contact in one call.
• Add an API to a gateway: serve these operations to AI clients.
• Generate and run API tests: test every operation in one run.
• The analysis: what the run read and what you can re-run.