Skip to content

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/:

LanguageFolderNeeds
C#clients/dotnet.NET 10 SDK
Pythonclients/pythonPython 3.9 or later
Goclients/goGo 1.22 or later
TypeScriptclients/nodeNode.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/me says 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 an Idempotency-Key so a submission can be sent again safely, polling the job until it has finished, and downloading each PDF with GET /v1/reports/{id}.
  • Handling errors: the API's {"error", "message"} body, a refused render's diagnostics, a successful render's warnings (X-Rfml-Diagnostics), the request id, and waiting out a rate limit (429 with Retry-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, which service doesn't have. Make a custom role with report.read under 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.