Send requests from an API client

This guide sends Foundation4 API requests from an interactive client instead of the command line: the documentation pages that every deployment serves, or a desktop API client with the collection that this documentation offers for download. Integrators and administrators use an API client to try operations and inspect responses before writing client application code. The client needs API access and an API key, as set up in Authenticate.

Client choice

Client	Installation	Location of saved requests	Typical use
Deployment pages	None: the API server serves the pages	None: the pages keep no requests	Single requests, including in an air-gapped deployment
Bruno	Open-source desktop application that needs no account	Collection files on the local disk	Saved requests on air-gapped or restricted workstations, and collections kept in version control
Postman	Desktop application; collections need a signed-in Postman account	The Postman cloud service, for a signed-in user	Teams that already use Postman on connected workstations

Postman, Bruno and other API clients such as Insomnia import the same collection, described in Collection.

API access

The client sends requests to the base URL in FOUNDATION4_URL, as set in API access: http://localhost:8080 through a kubectl port forward, or the host name of an installation with an ingress or a Gateway. A client on a workstation without kubectl access reaches a port forward on another machine through an SSH tunnel:

ssh -N -L 8080:127.0.0.1:8080 operator@kubectl-host

operator@kubectl-host stands for the account and host name of the machine that runs the port forward. The tunnel forwards http://localhost:8080 on the workstation to the port forward until the command stops.

The client sends the key identifier in the x-api-key header and the secret in the x-api-key-secret header on every request except the welcome message and the health check. A key with the permissions of the task, such as the tutorial key from Authenticate or a key from Manage API keys and permissions, serves for exploration. The master key serves only for administration.

Deployment pages

The API server serves two interactive pages, which read the OpenAPI document of the installed version from /openapi.json:

Path	Page
/docs	Reference built with RapiDoc
/_docs-swagger	The same reference in Swagger UI

The pages load every asset from the API server, so both work in an air-gapped deployment. Both pages send requests to the API server that serves the pages.

1. Open /docs under the base URL in a browser on the machine with API access, such as http://localhost:8080/docs.
2. In the authentication section, enter the key identifier for api_key and the secret for api_key_secret. In Swagger UI, the Authorize button opens the same two fields.
3. Open the POST /login operation under Authentication and send the request.

Expected result: status 201, with the name of the key in the key field, as in Key check.

Uses and limits

The API server builds the OpenAPI document of the pages from annotations in the API server's code. The operations, parameters and field types on the pages therefore match the installed version, while the text on the pages is not checked against the server's behavior. The pages serve the following uses:

• Version check. The pages list the operations and fields of the installed release, including a release that differs from the release this documentation describes.
• Single requests. The pages send one request at a time with the key fields, on any deployment, including an air-gapped deployment with no other client installed.

The pages do not replace this documentation or an API client for the following purposes:

• Behavior. Summaries, descriptions and status codes on the pages are written by hand in the code. Most operations have no description, the 201 response of POST /login is described as a created API key, and some status codes that operations return are not listed. The endpoint reference of this documentation corrects these points from a review of the code and states the permissions of each operation, so where the two differ, the endpoint reference describes the behavior.
• Saved requests. The pages keep no requests between visits. Requests that a reader repeats or shares belong in an API client with the collection.
• Public exposure. The API server answers the documentation routes without an API key wherever the API is exposed. Paths without an API key in Security hardening describes the restriction of these routes in a production deployment.

Collection

This documentation offers the API as a collection in Postman format 2.1 for download: foundation4-api.postman_collection.json. The collection holds the following:

• Requests. Every operation of the endpoint reference, in folders named after the sections of the endpoint reference, with the request body of the operation's curl example.
• Key headers. Both key headers on every request that requires a key. Postman and Bruno set only the x-api-key header when they import the OpenAPI document instead, and the API server then rejects each request with HTTP 401 and Unauthorized: No API Secret Key specified.
• Query parameters. Required query parameters, set from variables. Optional parameters, such as list filters and pagination, are listed but disabled, and enabling a parameter adds the parameter to the request.
• Variables. Collection variables named after the shell variables of the curl examples, as the following table lists.

Variable	Value
FOUNDATION4_URL	The base URL. The collection sets http://localhost:8080
FOUNDATION4_API_KEY	The key identifier
FOUNDATION4_API_SECRET	The secret of the key, set as Bruno and Postman describe
PIPELINE_ID, DOCUMENT_ID and the other identifiers	Identifiers from earlier responses, empty in the collection

Bruno

1. Save the collection file.
2. In Bruno, import the file as a Postman collection, and choose the folder on the local disk where Bruno stores the collection.
3. In the collection settings, set FOUNDATION4_API_KEY, and set FOUNDATION4_URL if the base URL differs from http://localhost:8080.
4. Create an environment for the deployment with the variable FOUNDATION4_API_SECRET, marked as secret. Bruno stores secret values on the local machine, outside the collection files.
5. Select the environment, open Check an API key in the Authentication folder and send the request.

Expected result: status 201, with the name of the key in the key field.

Postman

1. Save the collection file.
2. In Postman, import the file.
3. Open the variables of the collection. Set FOUNDATION4_API_KEY, and set FOUNDATION4_URL if the base URL differs from http://localhost:8080.
4. Enter the secret for FOUNDATION4_API_SECRET in the Current value column only, and save. Postman keeps current values on the local machine and synchronizes initial values with the Postman cloud service for a signed-in user.
5. Open Check an API key in the Authentication folder and send the request.

Expected result: status 201, with the name of the key in the key field.

Request practice

• Single requests. Send requests one at a time. A collection run, such as Run collection in Postman or the runner in Bruno, sends every request in the collection, including the delete operations, with the identifiers that the variables hold at the time.
• Identifiers. Copy each identifier from a response into the matching variable before the request that uses the identifier, as the curl examples do with shell variables.
• Secrets. Keep the secret out of collection files, shared workspaces and version control. A secret that leaves the machine is replaced as Key rotation describes.