REST API OpenAPI - edmozley/freeitsm GitHub Wiki

๐Ÿ“ REST API: OpenAPI specification

FreeITSM publishes a machine-readable OpenAPI 3.0.3 description of the whole REST API. Point any OpenAPI-aware tool at it to import every endpoint, generate a client library, or drive a test suite โ€” no copying from the docs by hand.

[!NOTE] For a human, browsing walkthrough use the interactive docs page inside the product (System โ†’ API โ†’ Documentation, how to use it). The OpenAPI document is the same surface in a form tools consume.

[!IMPORTANT] openapi.json is not the same file as spec.json โ€” and it's an easy mix-up. api/v1/spec.json is FreeITSM's own internal catalogue format (the file a developer edits, described in Maintaining the API catalogue). openapi.json is the standard OpenAPI document generated from it โ€” the format Postman and code generators understand. You edit spec.json; openapi.json regenerates itself. Nobody edits openapi.json by hand.

spec.json  โ”€โ”€(generator: api/v1/lib/openapi.php)โ”€โ”€โ–บ  /api/v1/openapi.json
(our format, hand-edited)                            (standard OpenAPI, generated, tool-facing)

Where to get it

Every install serves the document from its own API, no key required (it is public documentation and contains no secrets โ€” only the shape of the API):

Format URL
JSON (canonical) https://your-server/api/v1/openapi.json
YAML https://your-server/api/v1/openapi.yaml

Both are the same document. JSON is the canonical form; YAML is provided for the tools and people who prefer it. Without URL rewriting the same content is at โ€ฆ/api/v1/openapi.php and โ€ฆ/api/v1/openapi.php?format=yaml.

The servers entry uses a relative URL (/api/v1), so the document is correct on every install without anyone editing a hostname โ€” a tool resolves calls against wherever it fetched the document from.

What it contains

  • All 203 operations across the 15 modules, grouped by tag (Tickets, Assets, CMDB, Network Mapper, โ€ฆ).
  • Typed response schemas โ€” roughly 200 reusable component schemas, referenced with $ref. Every field the API returns is described with its type and nullability, so a generated client gets real model classes rather than untyped maps.
  • Request bodies with worked examples for every POST/PATCH, drawn from the same example set as the interactive docs.
  • Per-operation errors โ€” the HTTP statuses and error codes each endpoint can return, so a client can branch on them.
  • The security scheme โ€” HTTP bearer authentication, applied to every operation.
  • The success code each operation actually returns โ€” 201 on creation, 200 otherwise โ€” read from the handlers themselves rather than assumed.

Using it

Postman / Insomnia

Import by URL: Import โ†’ Link โ†’ paste https://your-server/api/v1/openapi.json. You get a collection with every endpoint, its parameters, and example bodies ready to send. Add your API key as a bearer token at the collection level.

Swagger UI / Redoc

Point either at the JSON URL to get a browsable reference. (These render the document; the in-product docs page is the one wired to run live calls against your install.)

Generate a client library

Use openapi-generator or swagger-codegen against the JSON URL, e.g.:

openapi-generator-cli generate \
  -i https://your-server/api/v1/openapi.json \
  -g python -o ./freeitsm-client

The typed schemas mean the generated models carry the real fields and types. Generators exist for C#, Python, TypeScript, Go, Java, PHP, Ruby and many more.

Contract testing / mocking

Because the document is generated from the live route table and verified against real responses (see how it's kept correct), it is safe to use as the contract in tests, or to stand up a mock server (e.g. Prism) from it.

Keeping it fresh

The document is generated on each request from the route table, the docs catalogue and the typed schemas โ€” it is not a file anyone edits by hand, so it always reflects the API the install is actually running. There is nothing to regenerate or republish after an upgrade.

Notes

  • The version is 3.0.3, chosen for the widest tooling support.
  • Dynamic JSON payloads โ€” workflow conditions and actions, form field definitions, workflow-execution logs and trigger payloads โ€” are described as open objects, because their inner shape varies by design.
  • Request bodies are documented with worked examples and validated field-by-field by the API at call time; response bodies additionally carry full typed schemas.

See also: How the OpenAPI document is kept correct ยท REST API (how the API works) ยท Using the API documentation page.