Skip to content

API Script Library Developer Guide

Ed Mozley edited this page Nov 19, 2026 · 1 revision

πŸ› οΈ API script library - Developer Guide

(5.7.0.) For someone adding a script to System β†’ API β†’ Scripts, or changing the library itself. User side: API script library. Decisions: design.

πŸšͺ Front door

The library is files: script-library/powershell/<slug>.ps1 and script-library/python/<slug>.py. Each starts with a header of # @tag value lines, identical in both. includes/api_script_library.php reads the folder; api/system/api_keys/scripts.php serves the catalogue and the text; the Scripts tab on system/api/index.php shows it. Nothing is in the database, and nothing ever runs on the server.

Adding a script = two files + a test run + php tests/api-script-library.php. No code changes, no registration: a file in the folder with a valid header is in the library.

πŸ“ Files

File What it does
🟒 script-library/powershell/*.ps1, script-library/python/*.py The scripts
βšͺ script-library/.htaccess, web.config Deny direct requests (nginx: location ^~ /script-library/ in deploy/nginx/freeitsm.conf)
🟣 includes/api_script_library.php Header parser, catalogue, apiScriptRead()
🟣 api/system/api_keys/scripts.php GET catalogue · ?slug=&lang= text · &download=1 file. Admins only (admin_api_guard.php)
🟑 system/api/index.php, assets/js/api-scripts.js The Scripts tab
βšͺ lang/*/system.php api.tab_scripts, api.scripts.* (module names reuse common.modules.*)
🟒 tests/api-script-library.php The guard - runs in CI (web-exposure.yml)
βšͺ api/system/debug-tools/D009_guarded_paths.php Probes that script-library/ is not served

🏷️ The header

# @title       Export open tickets to a CSV file
# @summary     One sentence: what it does for the reader.
# @module      tickets            (a common.modules key, or "general")
# @changes     no                 (yes = it writes; must preview unless -Apply / --apply)
# @level       starter            (starter | intermediate | advanced)
# @endpoints   GET /tickets, GET /statuses
# @permissions tickets.read, reference.read      ("none" for /ping only)

# comments in both languages, so one parser reads both. A long @endpoints or @permissions continues on following lines that start with # and at least six spaces. {id} stands for any id in a path.

βœ… What the guard checks, and why each rule exists

Rule Why
Every tag present and valid; the two headers identical The screen reads one of them; they must not disagree
Both languages exist The library promises PowerShell and Python
Each @endpoints entry matches a real route in api/v1/lib/routes.php A renamed endpoint breaks the build, not a user's migration
@permissions = exactly the permissions those routes need The page tells people which key to make; too few fails at run time, too many teaches over-privileged keys
Every API path in the code is in @endpoints The header must be the whole truth about what the script touches
No fitsm_… key in the text A pasted key in a shipped file would be public
@changes yes β‡’ [switch]$Apply / '--apply' Nothing that writes runs by accident
Python imports standard library only Runs anywhere Python runs, no pip
Python parses (ast.parse); PowerShell parses (the PowerShell parser, through a temp .ps1) A syntax error never ships. The parse check uses a file, not -Command, because on Linux CI the shell would expand $e and $PSVersionTable inside a double-quoted command and the check would silently do nothing
The folder is denied on Apache, IIS and nginx, and D009 probes it On some hosts a .py in a web folder runs as CGI

The guard is static - no database, no network. It does not replace running the script: every script is run against a test install (preview, then apply) before it ships.

✍️ Writing a script

Copy check-your-api-key (reads) or knowledge-migration (writes) and keep their shape:

  • Settings: -Url / --url (else FREEITSM_URL); key from FREEITSM_API_KEY, else -KeyFile / --key-file (default api-key.txt beside the script). Base = URL + /api/v1.
  • One helper that sends the Bearer key, returns .data, and stops with FreeITSM's own error message.
  • Writes preview by default; the preview makes no write calls.
  • Look things up, don't hardcode ids - statuses, types, impact levels come from the reference endpoints.
  • Comments say why, not just what: the API behaviour relied on, and what a reader changes for their own install. Plain English, plain hyphens.

TRAP (PowerShell 5.1): never send text read with Get-Content through ConvertTo-Json. Get-Content tags the string with hidden PSPath / PSDrive / PSProvider properties, and ConvertTo-Json -Depth 10 walks the whole provider object graph - it effectively never finishes. Use [IO.File]::ReadAllText(). Found building the Knowledge migration demo.

TRAP (PowerShell 5.1): send JSON as UTF-8 bytes ([Text.Encoding]::UTF8.GetBytes(...)); a plain string body is sent in the system code page and mangles accented names.

πŸ”’ The page

  • apiScriptRead() finds a file through the catalogue built from the folder listing; the slug must match ^[a-z0-9-]+$ and the language must be powershell or python. No path is built from the request.
  • The text is shown with textContent only; comment lines are spans built the same way. Downloads: text/plain, attachment, nosniff, no-store.
  • Deep link: system/api/?tab=scripts&script=<slug>&lang=python. api-scripts.js reads it when the page loads, because showTab() rewrites the address to ?tab=scripts before the library has loaded.

Related: REST API Β· Knowledge migration API - Developer Guide

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally