Sample API clients
Your applications render reports through the HTTP API. Sample clients in four languages show how, in the public report-server-releases repository, under clients/:
| Language | Folder | Needs |
|---|---|---|
| C# | clients/dotnet | .NET 10 SDK |
| Python | clients/python | Python 3.9 or later |
| Go | clients/go | Go 1.22 or later |
| TypeScript | clients/node | Node.js 22.18 or later |
Each uses only its language's own HTTP client and JSON support, and is under the MIT licence: copy it into your application and change it as you like. The samples' README says how to run them.
What they show
Each sample does the same things, against the Letter to customers example from the gallery:
- Authenticating with an API key, sent as
Authorization: Bearer <key>.GET /v1/mesays what the key may do. - Listing the templates, with the environments each is published in.
- Rendering a PDF straight away with
POST /v1/render, from the application's own data. - Rendering a batch in the background with
POST /v1/jobs, with anIdempotency-Keyso a submission can be sent again safely, polling the job until it has finished, and downloading each PDF withGET /v1/reports/{id}. - Handling errors: the API's
{"error", "message"}body, a refused render'sdiagnostics, a successful render's warnings (X-Rfml-Diagnostics), the request id, and waiting out a rate limit (429withRetry-After). - Listening to
GET /v1/events, and connecting again after the server restarts.
They find the report made from the example by its name, Letter to customers, because its id depends on how it was made: New report makes it from the title, letter-to-customers, and an empty catalog's Start from an example keeps the example's own, customer-letter. REPORT_TEMPLATE names a template by its id instead.
The API key
An application authenticates with an API key, not a person's password. An administrator makes one under Admin → API keys (the administration site), and its secret is shown once.
- Give it the built-in service role to read templates and render.
- To download stored reports, as a background job's results are, it also needs
report.read, whichservicedoesn't have. Make a custom role withreport.readunder Admin → Roles and give the key both. - Each key has its own rate limits (rate limits).
Name the environment in each render ("environment": "prod"). A request that names none renders from the first environment, dev on an install with several.
Generating a client
The API reference is made from reportd's OpenAPI 3.0 description, api/openapi.yaml. Every operation in it has an operationId, such as render, createJob or getReport, so a client generator gives its methods stable names. They are camelCase and unique, and an id stays as it is from one release to the next unless its route changes.