Analyze an API made of several services

A backend made of several services is one API in Faustine: one namespace, one sign-in, one set of versions. Each service has its own code and its own analysis. Use this for REST services that share a host behind an edge which forwards by path, such as nginx, Kong or a cloud API gateway.

A backend-for-frontend or an orchestrator that declares its own routes is one service. Create it with Create an API.

Before you begin

• The code of each service, in repositories Faustine can read or as ZIP files. See Connect GitHub.
• The public prefix of each service: the path the edge puts in front of its routes, such as /billing.

Create the API

1. In the portal, go to APIs and select New API.
2. In API type, select REST.
3. In Architecture, select how the code is laid out, then Continue:
   • Several services, one repository: each service is a folder of the same repository.
   • Several services, several repositories: each service has its own repository or archive.
4. In Details, enter the API name and the Namespace that all the services share, then select Continue.
5. In Services, add the services. The steps depend on the architecture.
6. In Keep the API up to date, select Automatic or Manual. The step appears when at least one service comes from a repository.
7. In Review & analyze, select Create & start analysis.

An API can have up to 20 services.

Add services from one repository

1. Select the repository and the branch.
2. Select Find services. Faustine lists the folders whose manifest declares an HTTP server, such as a package.json, go.mod, pyproject or pom file. Nothing is analyzed at this point.
3. Select the services that belong to this API.
4. For each one, check the Name, the Namespace and the Public prefix.

To add a folder that was not found, select Add service manually and enter its Folder.

Add services from several repositories

1. Select Add a service.
2. Connect the service's repository, or upload its ZIP.
3. Enter its Name and Namespace. The Language & framework field defaults to Let the analysis detect it.
4. Enter its Public prefix. If the service already registers its routes with the full public path, select No prefix — the service registers the full public path.
5. Select Save service.

Repeat for each service. Two services cannot share a prefix, and a prefix is a fixed path without parameters.

What happens after you create the API

The portal opens the API's Services tab. Faustine analyzes the services one at a time, and the operations of each service join the draft when its analysis finishes. You can review them while the next service runs.

The analysis looks for the service that issues the credentials the others accept. That service gets the Auth provider badge, and its sign-in becomes the sign-in of every service. If no service issues credentials, set the sign-in in the Authentication tab. See Authentication.

The analysis of a service does not publish a version. When the services you need are ready, select Publish. All of them go into the same version. You can publish while another service is still in the queue.

Manage the services

The Services tab lists each service with its public prefix, its code and the state of its analysis. Each row has a menu:

Add service adds one to an existing API, including an API that was created as one service. In that case the current code becomes the first service with no prefix, and no operation key or path changes. From then on, every analysis goes into the draft and you publish it yourself.

When you remove a service, published versions keep its operations until you publish again.

Find a service's operations

In the Operations tab, operations are grouped by service and then by resource. The row of chips over the table filters the list to one service.

Next steps

• The analysis: what each service's analysis writes.
• Authentication: set the sign-in when no service issues credentials.
• Versions and updates: publish the draft once the services are ready.