Skip to main content

Register trainee teachers - FauAPI integration

Find and Use an API (fauapi) is DfE's central API catalogue. We publish the Register API spec there so it shows up in the directory.

Current status: pre-prod only

We're currently only publishing to FauAPI pre-prod. The FauAPI platform has several bugs (see below) that make the production catalogue unreliable — schemaUrl, baseUrl, and publish responses are all broken on their side. We've reported these and they're aware. Once they're resolved, we'll switch the workflow to target production.

How it works

On every deploy to production, a GitHub Actions job (update-fauapi-catalogue in build-and-deploy.yml) runs bin/generate_fauapi_manifest to build the manifest JSON from config/settings.yml and the openapi yaml files in public/openapi/, then POSTs it to the fauapi platform API and publishes it. Import is idempotent by name — repeat imports update rather than duplicate.

The manifest is generated fresh in CI on every deploy — nothing to keep in sync manually. You can run the script locally to inspect the output:

ruby bin/generate_fauapi_manifest

Setup that was done

Pre-prod required manual one-time setup in the fauapi management portal. The workspace already exists — to get access, ask an existing dev on the team to add you.

The linked API was created via import with name: "register-trainee-teachers-api", displayName: "Register trainee teachers API". Note: displayName is globally unique across all fauapi workspaces. The CI workflow keeps it updated on each deploy.

A FAUAPI_PP_AUTOMATION_TOKEN secret is needed in GitHub Actions — this is a bearer token from the fauapi pre-prod management portal.

Production workspace setup hasn't been done yet. When the platform bugs are fixed, create the workspace + API at apimanagement.education.gov.uk, generate a FAUAPI_AUTOMATION_TOKEN secret, and update the workflow to target the production URL.

Environment Management portal Catalogue
Pre-prod pp-apimanagement.education.gov.uk pp-find-and-use-an-api.education.gov.uk
Production apimanagement.education.gov.uk find-and-use-an-api.education.gov.uk

Known issues (as of March 2026)

The fauapi platform API has some bugs we've reported:

  • schemaUrl and schemaType in the import payload are silently ignored — the OpenAPI spec doesn't get attached
  • baseUrl on environment objects is silently dropped
  • Publish endpoint returns { "status": 400 } in the body with HTTP 200 — acknowledged as their bug
  • Import response doesn't include the API id — we work around this by listing APIs after import