Web API

Applies to: BarcoderX Basic and Ultimate

Status: Planned. Nothing is released yet and there is nothing to download. This page lists the first version of the API as it is planned. Paths and behavior can change until the first release. After that, version 1 changes only by adding to it.

What the web API is

The API server that you install and run offers a REST API, so a program in any language can create labels, make files and print. Everything it stores stays in your own database. BarcoderX hosts nothing, and no labels, templates or print data ever reach BarcoderX. The API lives under /api/v1, and an OpenAPI document describes it. The label editor uses the API and nothing else. .NET developers also get BarcoderX.Client, a typed client for every operation.

The API belongs to the server that you run. A second host, the stateless render host, serves the rendering parts only. See below.

A documentation page will be generated from the OpenAPI document in English and Spanish, with a curl example for each operation. It does not use any third-party documentation viewer.

How the API behaves

Versions. The version is in the path. Within version 1, BarcoderX only adds things: new endpoints, new optional request members, new response members. A breaking change would create /api/v2, and version 1 would keep running for at least 12 months after that. Every response lists the versions that the server supports, and a version that is being retired carries Deprecation and Sunset headers.
Errors. An error is a problem details document (RFC 9457). It has a type that links to the documentation, a stable code made of BX and four digits, a title and a detail in your language, a list of diagnostics that names the element and the place in the template, and a trace ID. The language comes from the Accept-Language header, then the default of your server, then English.
Retrying safely. Requests that create something, print jobs, batch jobs and sequence allocation accept an Idempotency-Key header. BarcoderX keeps the answer for 24 hours, so repeating the request returns the same answer. The same key with a different body is refused with 422. A duplicate that arrives while the first is still running gets 409.
Editing safely. Stored items return an ETag. A template update must send If-Match. A change by someone else answers 412, and a missing header answers 428.
Rate limits. Requests are rate limited, and there is a limit on simultaneous render requests. When you go over, the answer is 429 with a Retry-After header.
Size of a request. A synchronous request can ask for up to 100 labels, or as many as fit the pixel budget. A larger request is accepted with 202 and runs as a job. A job reports progress, can be canceled, keeps its output for a limited time and can call a webhook when it finishes. Webhooks are signed with HMAC-SHA-256 over the time and the body, and are retried with growing pauses.
Lists. Lists use a cursor and return at most 200 items at a time.
Strict input. Bodies are size-limited and checked strictly. Members that BarcoderX does not know are rejected, except inside a template.
Health checks. /health/live and /health/ready need no sign-in and reveal no stored data.

Diagnostic codes have the form BX and four digits. The first digit groups them by area:

Range	Area
1000 to 1999	Model and templates
2000 to 2999	Data and expressions
3000 to 3999	Graphics, imaging, fonts, text and export
4000 to 4999	Barcodes
5000 to 5999	Commands and printing
6000 to 6999	The API
7000 to 7999	The print agent
8000 to 8999	The editor
9000 to 9999	Licensing

Every code will have its own documentation page in English and Spanish.

The planned first version

Paths are relative to /api/v1. Everything in the table is planned for the first release, except where the last column says otherwise. Sign-in and permissions are in Authentication and access.

Resource	What it is for	Methods and paths	Release
Templates	Store, version, publish, validate and convert templates	`GET, POST /templates`; `GET, PUT, DELETE /templates/{id}`; `GET /templates/{id}/versions`; `GET /templates/{id}/versions/{n}`; `POST /templates/{id}/versions/{n}/restore`; `POST /templates/{id}/publish`; `PUT /templates/{id}/draft`; `POST /templates/validate`; `POST /templates/convert`	First
Template archives	Move a template with its fonts and images between servers	`GET /templates/{id}/archive`; `POST /templates/import-archive`	First
Render and export	Make a label file from a stored or inline template and data. Formats: PNG, JPG, PDF, SVG, PCX and HTML, and EPS later.	`POST /render`; `POST /render/elements`; `POST /render/thumbnail`	First (EPS later)
Commands	Make the printer commands for a template and data	`POST /commands`	First
Batch jobs	Run large renders in the background	`POST /jobs`; `GET /jobs/{id}`; `GET /jobs/{id}/output`; `DELETE /jobs/{id}`	First
Print jobs	Send labels to printers	`POST /print-jobs`; `GET /print-jobs`; `GET /print-jobs/{id}`; `POST /print-jobs/{id}/cancel`	First
Printers	Register printers, read their status, list printer languages and profiles	`GET, POST /printers`; `GET, PUT, DELETE /printers/{id}`; `GET /printers/{id}/status`; `GET /printer-dialects`; `GET /printer-profiles`	First
Agents	List print agents, start enrolment, revoke an agent	`GET /agents`; `POST /agents/enrollments`; `DELETE /agents/{id}`	First
Barcodes	List symbologies, check data, make one barcode	`GET /barcodes/symbologies`; `POST /barcodes/validate`; `POST /barcodes/encode`	First
Assets	Store fonts and images	`GET, POST /assets/fonts`; `GET, POST /assets/images`; `GET /assets/{id}`; `GET /assets/{id}/content`; `DELETE /assets/{id}`	First
Data	Stored data sources, field discovery, and sequences	`GET, POST /data-sources`; `GET, PUT, DELETE /data-sources/{id}`; `POST /data-sources/infer-schema`; `GET, POST /sequences`; `POST /sequences/{id}/allocate`	First
Expressions	List functions, check and try out expressions, store macros	`GET /expressions/functions`; `POST /expressions/validate`; `POST /expressions/evaluate`; `GET, POST /expressions/macros`; `PUT, DELETE /expressions/macros/{id}`	First
Metadata	Describe element properties, the limits in force and the license state	`GET /meta/elements`; `GET /meta/limits`; `GET /meta/licence`	First
Administration	API keys and the audit log	`GET, POST /api-keys`; `DELETE /api-keys/{id}`; `GET /audit-events`	First
Printer maintenance	Pause, resume, cut, calibrate and similar operations	`POST /printers/{id}/maintenance/{operation}`	Later

Notes on some of these:

POST /barcodes/encode returns an image in any released format, chosen with the Accept header, or a JSON document with the module data and details, or a base64 data URI. Asking for a format that has not been released answers 406. Data problems answer 422 with the diagnostics.
POST /commands and each label set of a print job accept options that only one printer language has. An option that the language does not offer is refused with 422.
GET /meta/licence shows the license state and never the key. See Editions and licensing.
/openapi/v1.json serves the OpenAPI document. It is not under /api/v1.

The stateless render host

The stateless render host is a smaller host of the same engine. It is planned as a container image for Linux x64 and Linux arm64. It has no database and no stored templates. It serves /render, /commands, /barcodes, /expressions and /meta, and it takes a complete template in each request.

A single API key protects it. The host refuses to start without one, and its message names the missing setting.
You set it up in a settings file next to the host, or with environment variables or the command line.
Fonts and images come from the request, or from a folder that the operator registers at start-up.

BarcoderX is a product of P4 Software.

Was this page helpful?

Previous Font support Next Authentication and access