REST API Documentation Page - edmozley/freeitsm GitHub Wiki

🧭 Using the API documentation page

FreeITSM ships an interactive API reference at System β†’ API β†’ Documentation. It's more than documentation β€” it's a workbench: browse every endpoint, click worked examples, watch request code rewrite itself in seven languages as you type, and see live responses from your own install. This page is the tour.

[!NOTE] The docs page documents the REST API v1. Each module also has a written usage guide on this wiki (linked from every endpoint page and the sidebar) β€” the docs page is for doing, the wiki guides are for understanding a module's model.

πŸ—ΊοΈ The layout β€” three panes

Pane What it's for
Left β€” navigation A search box and a collapsible tree of every endpoint, grouped by module, each with a colour-coded method badge (🟒 GET, πŸ”΅ POST, 🟠 PATCH, πŸ”΄ DELETE). The endpoint you're viewing is highlighted.
Middle β€” the endpoint explainer One endpoint at a time: what it does, the permission it needs, its parameters as a fill-in form, its error codes, and clickable worked examples.
Right β€” the live code pane Your API key, the request in your chosen language (rebuilt live), the response from your install, and the Send button.

No more scrolling one giant list β€” you navigate, and each endpoint gets a page of its own.

πŸ” Search

Press / anywhere (or click the search box) and type. The tree filters live across endpoint paths, summaries and descriptions β€” so warranty finds the asset lifecycle filters, fire finds the workflow test-fire, and typing a method like patch shows everything updatable. Matching sections auto-expand; clear the box to restore the full tree.

πŸ”— Shareable URLs

Every endpoint has its own hash URL β€” …/docs.php#post-tickets, …/docs.php#get-network-diagrams-id-suggestions. Bookmark them, paste them in tickets or chat, and the back/forward buttons walk your browsing history like a wiki.

πŸ“– The Overview page

The landing page (πŸ“– Overview & errors at the top of the tree) covers what's identical everywhere so endpoint pages don't repeat it:

  • Authentication β€” keys from the API keys page, sent as Authorization: Bearer fitsm_…
  • The response envelope β€” {"data": …}, pagination meta, {"error": {code, message}}
  • Rate limits β€” 60/min per key by default, and the X-RateLimit-* headers
  • The full error-code glossary β€” every HTTP status and error slug the API can return, in one table
  • Links to every module's wiki guide

πŸ“„ An endpoint page, top to bottom

  1. Method + path + permission. The πŸ”‘ resource.action pill is exactly what you tick when creating a key β€” if a call returns 403, this is the box that wasn't ticked.
  2. Wiki link. Jumps to the module's full usage guide here on the wiki.
  3. Description. What the endpoint does, including behaviours unique to the API (stricter validation, extra filters the UI doesn't have).
  4. Worked examples β€” see below.
  5. Parameters as a form. Every path and query parameter is a real input field with its description beside it. Type into them and watch the right-hand pane react. For POST/PATCH endpoints there's a JSON body editor, pre-seeded with a realistic payload β€” its border turns red while the JSON is invalid.
  6. Errors table. Which errors this endpoint can return and exactly what triggers each β€” the generic ones (401, 403 with the required permission named, 404 on {id} routes, 422 on writes, 429) plus the endpoint-specific ones: the CAB-vote conflicts, frozen-version 409s, duplicate-node rules, the calendar's naive-datetime 422, and so on.

πŸŽ“ Worked examples

Nearly every endpoint carries clickable example chips (~450 across the API), written to teach by escalation:

  1. the simplest possible call,
  2. parameters combined β€” filters stacking with search and pagination,
  3. a realistic integration scenario β€” "monitoring probe opens an incident", "nightly sync via updated_since", "discovery agent draws a switch".

Clicking a chip fills the parameter form and body editor β€” the code sample rewrites instantly and (for GETs) the live response refreshes. It's the fastest way for a beginner to get a feel for how parameters can be used and combined: click through the three, watch what changes.

πŸ’» The live code pane

Seven languages: cURL, PowerShell, PHP, Python, C#, Ruby and JavaScript, as tabs. The sample is generated from the endpoint definition plus your current form values β€” type an id, add a query filter, edit the body, switch tabs, and the code follows in real time. Your language choice is remembered.

  • Samples always show YOUR_API_KEY rather than your real key, so they're safe to paste into scripts, tickets and documentation.
  • Copy buttons on both the request and the response.

⚑ Live responses

Paste an API key once at the top of the code pane β€” the dot beside it turns green when the key verifies (it's checked against /ping). The key lives only in your browser's localStorage and honours the key's permissions, company scope and rate limit, exactly like a real integration.

Then, as you browse:

  • GET endpoints fire automatically β€” select one (fill in its {id} if it has one) and the real response from your install appears. Responses are cached while you browse, so flicking between endpoints doesn't re-hit the rate limit; a cached response says so, and Send refreshes it.
  • Writes never fire on their own. POST, PATCH and DELETE run only when you press Send β€” browsing the docs can't create, change or delete anything.
  • The response bar shows the HTTP status and your remaining rate-limit budget.

[!TIP] For a browsing session, use a key with only read permissions β€” then even pressing Send on a write endpoint can do no harm. Keep a second, write-capable key for when you're deliberately testing writes.

[!WARNING] Send is real. A POST /tickets from the docs page creates an actual ticket, fires the workflow engine and sends any configured emails β€” exactly like the UI. That's the point, but it's worth remembering.

🧩 For contributors β€” where the content lives

The page is data-driven with no build step: it reads the endpoint catalogue from api/v1/spec.json β€” the single source of truth, shared with the OpenAPI generator. Each entry carries a method, path, permission, summary, description, parameters, worked examples and endpoint-specific errors, keyed "METHOD /path". Adding an API endpoint means adding one entry to spec.json (scaffold a starter with php api/v1/dev/openapi_stub.php); the navigation, search, code generation in all seven languages, error derivation, and the OpenAPI document all update from that one edit. The self-check (api/v1/lib/openapi_check.php) validates every entry is well-formed and matches a real route.

See also: REST API (how the API works under the hood) Β· the per-module usage guides in the sidebar.