API integration

An API is a promise to someone else’s code. Whoever builds against it will rely on field names, formats and behaviour, long after its builders have moved on. That is why we start with the contract, not the implementation.

We have built against many APIs we do not control ourselves, including a large number of iGaming game providers and a long list of payment solutions. Every provider has its own way of authenticating, versioning and reporting errors, and that is usually where the time goes.

The contract first

A specification checked in alongside the code can be reviewed in a pull request, and a change to a field shows up in the diff before it reaches production. The specification also lets whoever will use the API start building before the service exists, against a mock generated from it.

Decide on versioning before you need it

Decide from the start what may change within a version and what needs a new one. A rule we work by: within a version, new fields may be added, but an existing field may not change meaning, become required or disappear. New fields in requests must be optional, because a new required field is a breaking change. Everything else gets a new version, with a set date for when the old one closes.

What we build in by default

• Write calls that can be sent again, so a retry after a timeout does not create a duplicate.
• Pagination from the start. A list with no upper limit works in testing and grows in production until it does not.
• Proper status codes, not an error message in a response with status 200.
• Timestamps in UTC when they mark an exact moment. Dates, bookings and periods get the time zone or calendar they need to be read correctly.
• Monitoring that alarms when a flow stops delivering.

When do you not need a contract?

The contract exists as soon as someone calls the service, written down or not. The question is how much formality it deserves. If you own both sides and can change them in the same release, a checked-in specification is mostly a formality. If another team needs to know before you rename a field, it is not. When the API has to meet an ERP, see ERP integration.