"Open architecture" is one of those phrases that appears in every sales proposal for public-sector software. In practice, though, what the client receives can vary enormously: from a poorly documented generic endpoint to a complete API with SDKs in several languages. At Labrax we have a very specific view of what it means for software to be genuinely integrable, and this article describes that view.
The underlying problem: public-sector legacy
A medium-sized public administration may have between 15 and 40 operational systems in production at once: case management, notifications platform, payment systems, municipal register, e-government portal, corporate intranet, HR systems, residents' CRM, vertical platforms for specific departments... When a new piece of software joins the ecosystem, the question that matters is not whether it is good, but whether it is able to coexist.
Coexistence has two dimensions:
- Receiving data from existing systems (querying the municipal register, validating identity, reading case files).
- Sending data to existing systems (publishing notifications, registering entries on the e-government portal, feeding the CRM).
Both directions require APIs. If software does not expose an API, it forces the client to live on an island. If it exposes one but does not document it, it is pretending to be integrable when in fact it is not.
Our standard: REST + OpenAPI 3.0
All our products expose a REST API with an OpenAPI 3.0 specification. This means that:
- The structure is predictable (standard HTTP verbs, correct status codes, JSON responses).
- The documentation is versioned as code, generated from the source code itself, with no possibility of divergence between what is documented and what is real.
- Any client can use standard tools (Postman, Insomnia, Swagger UI) to explore and test the API.
- SDKs can be generated automatically in any language from the OpenAPI file.
Authentication: OAuth2 with JWT
The standard flow is OAuth2 Client Credentials for machine-to-machine integrations and Authorization Code with PKCE for flows involving a human user. Tokens are short-lived JWTs (1 hour), with rotating refresh tokens.
For public administrations there is an important nuance: systems that require a qualified digital identity (Cl@ve, FNMT, certificates) connect through the client's e-government portal, not through our API directly. Our API delegates authentication to the corporate identity manager.
Versioning: semver and backwards compatibility
The API is versioned with explicit semver in the URL (/api/v1/recursos). When a breaking change is introduced, the major version goes up (v2) and v1 remains operational for at least 24 months to give clients time to migrate.
Additive changes (new fields, new endpoints, new error codes) do not break compatibility and do not require a version change. This lets the software evolve without forcing clients to update their integrations constantly.
Common integration patterns
Real-time data queries
This is the simplest pattern. The client makes a GET request and we respond with the data. Recommended for small amounts of data, one-off queries and cases where latency matters.
Example: checking whether a number plate has an active LEZ permit.
Webhooks for notifications
When the client wants to react to events in our system (a new fine, an expired permit), it should not poll. We configure a webhook: when the event occurs, our system sends an HTTP POST request to the client's endpoint with the structured information.
This requires the client to have an exposed, cryptographically signed endpoint to validate that the call really comes from us.
Bulk import (bulk operations)
For initial loads or periodic synchronisation, per-record APIs are inefficient. We expose bulk endpoints that accept up to 1,000 records per request and return an operation identifier that the client can query later to check the status.
Streaming events (Server-Sent Events)
For cases where the client needs to observe changes in real time (such as a dashboard showing fines as they happen), we expose SSE endpoints. They are lighter than WebSockets and compatible with any standard HTTP proxy.
Idempotency: the detail that prevents the most expensive problems
Public APIs in the public sector have a specific problem: administrations' networks tend to have aggressive firewalls, unstable proxies and intermittent connections. A POST operation can fail midway and the client does not know whether it reached the server or not.
The solution is idempotency: each create operation carries a unique key (Idempotency-Key) generated by the client. If the client retries the same operation with the same key, the server recognises that it has already processed it and returns the original response without duplicating the action.
This avoids the problem of "duplicate fines" or "triplicate permits" when there is a retry after a timeout.
Documentation: the most neglected factor
An API without good documentation is essentially an API that does not exist. Our standard includes:
- A complete OpenAPI 3.0 specification, browsable with Swagger UI or Redoc.
- Request and response examples for every endpoint, with representative data.
- Quick-start tutorials for the most common flows (authentication, first query, error handling).
- Documented error codes with a description and recommended action.
- Specific integration guides for systems commonly used in the public sector.
- Exportable Postman collections so you can start testing straight away.
- A public sandbox where the API can be tested without affecting production.
Structured errors
Errors follow the RFC 7807 format (Problem Details for HTTP APIs). Instead of returning a free-text message, we return a structured object:
{ "type": "https://labrax.es/errors/authorization-not-found", "title": "Permit not found", "status": 404, "detail": "Number plate 1234ABC has no valid permit.", "instance": "/api/v1/authorizations?plate=1234ABC" }
This lets clients handle errors programmatically, distinguishing between different types of failure (authentication, validation, resource not found, conflict, internal error) and reacting appropriately.
Compatibility with the Spanish National Security Framework
Our APIs meet the requirements of ENS High:
- Mandatory TLS 1.3 encryption (TLS 1.2 minimum for compatibility).
- Audit logs of all operations, retained for 24 months.
- Unambiguous identification of the user or system carrying out each operation.
- Traceability of state changes in any resource.
- Encryption of personal data at rest (AES-256).
What we ask of clients
Integration works both ways. For it to work well, we also ask the client to:
- Have a technical team (in-house or external) that understands HTTP and JSON.
- Keep test environments separate from production.
- Handle retries and transient errors correctly.
- Not store credentials in source code.
If your organisation is evaluating an integration with our products or you have questions about how to approach it, we can carry out a free technical analysis before deployment.
