Custom OpenAPI integration
More and more systems publish an OpenAPI description: a JSON or YAML file that defines which requests an API accepts and what it returns. For the Dutch government, the OpenAPI Specification is mandatory when describing REST APIs, and the Logius API Design Rules require it too. Appfront builds integrations with systems that publish such a specification: we read the contract, generate the client, validate every request and catch new versions before they break anything.
What is an OpenAPI-based integration?
An OpenAPI-based integration uses the published description of an API as its contract. The OpenAPI Specification describes which data an API accepts as input and returns as output, independent of programming language, in a YAML or JSON text file. It is maintained by the OpenAPI Initiative, an open community set up by the Linux Foundation, and is now at version 3.2. Because the description is machine-readable, we can generate code from it and validate every request and response against it, instead of copying the documentation by hand.
In 2018, Forum Standaardisatie (the Dutch Standardisation Forum) added the OpenAPI Specification to its 'comply or explain' list for describing or specifying a REST API in government and the (semi-)public sector. On 29 September 2026 it was decided that this status also applies to version 3.1, effective 1 January 2027; according to the Forum, 3.1 is not fully interchangeable with 3.0. The Logius REST API Design Rules, also mandatory, require that an API's documentation is an OpenAPI description, that it can be retrieved as JSON without logging in, that the major version number appears in the URL, and that every API publishes a changelog and a deprecation schedule.
We build custom integrations because an integration is more than calling endpoints. Which data from your system goes to the API, how you authenticate, what happens when the API returns an error and how you handle a new version all determine whether the integration is reliable. Not every specification is complete or matches exactly what the API does. That is why we first test the contract against the real API and record any deviations, before any production data passes through it.
Based on the contract
The specification as the foundation.
Checked
Every request validated.
Ready for new versions
Changes spotted in time.
How we build your OpenAPI-based integration
We start with the API and your goal: which specification the system publishes, which version of the OpenAPI Specification it follows, how authentication works and which data you want to exchange with which of your own systems. Then we read the contract, generate a client and test it against a test or acceptance environment from the provider, if one is available. We build the flow that delivers the most value first and have you review it with real data. Other endpoints follow once that works well. After that we monitor the specification: if a new version or a changelog entry appears, we can see which parts of the integration are affected.
Specification, version, access.
Generated and tested.
Most value first.
Go-live, monitoring, and maintenance when new versions arrive.
What an OpenAPI-based integration actually does
The components below appear in almost every integration based on an OpenAPI specification. Which ones you need depends on the API and on your own systems.
Client
Generated from the contract.
Validation
Request and response validated.
Versions
Changes flagged.
Mapping
Fields mapped to your system.
Access
Keys and tokens kept secure.
Log
Every request traceable.
Who we build OpenAPI-based integrations for
The integration is intended for organisations that want their own system to communicate with an API described by an OpenAPI specification. The more requests and the more important the data, the more a validated integration delivers.
Farms
Integrating with suppliers.
Government bodies
APIs that follow the rules.
Chain partners
Data between organisations.
Software builders
Your software, connected to an API.
Technology and integrations
This page is about integrations with an API published by someone else. If you want to design and document an API yourself, see our page on an API-first platform or on the API developer. If you are integrating with government APIs, see our page on the Haal Centraal integration and the one on ZGW APIs. You can read about our approach on building software.
Why Appfront for your OpenAPI-based integration?
An integration that quietly breaks because the provider renamed a field, a request that is rejected without anyone noticing, or documentation copied by hand that is no longer accurate all cost time and produce incorrect data. That is what we build against: the contract as the foundation, checks on every request and monitoring of new versions.
Based on the contract
No retyped documentation.
Checked
Deviations spotted immediately.
Resilient
New versions anticipated.
Security and privacy in an OpenAPI-based integration
The integration only uses the endpoints and fields needed for your purpose, with its own account or key that has exactly the rights required. Every request is logged with its time and result. If personal data passes through the integration, the GDPR applies and we send and store no more than necessary.
The integration runs in a European data centre, with encrypted connections and storage. API keys, tokens and certificates are kept secure and are not visible to staff. We agree with you in advance who in your organisation may see the data from the integration.
Frequently asked questions about an OpenAPI-based integration
Questions that IT managers, architects and product owners ask before they start.
A standard for describing an HTTP or REST API, independent of the programming language. The description is a JSON or YAML file that defines which requests an API accepts and what it returns. The standard is maintained by the OpenAPI Initiative, an open community set up by the Linux Foundation.
An integration that uses the published description of an API as its contract. We generate the client from it, check every request and response against it and use a new version of the specification to see which parts of the integration are affected.
Yes, for describing or specifying a REST API, the OpenAPI Specification has been on Forum Standaardisatie's 'comply or explain' list since 2018. It has been decided that this status will also apply to version 3.1 from 1 January 2027. In addition, the REST API Design Rules require an OpenAPI description.
According to Forum Standaardisatie, version 3.1 is not backward compatible with 3.0: it contains changes that can break existing descriptions and tools. A 3.1 specification may therefore contain elements that older tools do not read properly. We establish which version an API uses in the first step.
That happens. That is why we first test the contract against the real API, in a test environment if there is one. We record any deviations and, where possible, report them to the provider, so that the integration does not rest on an incorrect description.
The integration monitors the specification and the changelog. When something changes, we see which endpoints and fields are affected and adapt the integration before the old version disappears. Under the API Design Rules, government APIs publish a deprecation schedule for this.
For organisations that exchange process-critical data through an API, or that integrate with several APIs. For a single, simple call, a standard integration tool is sometimes enough.
Integrating with an API that uses OpenAPI?
Tell us which API you want to integrate with and which system it belongs to. We'll show you how an integration built on the contract handles it reliably.