Skip to content
Balkan Tecnologia
AccessibilityGet in touch
Balkan Tecnologia

APIs with a clear contract, versioning and documentation

We design and build APIs for your website, your app and your partners, with the contract written before the code, plus versioning and tests.

A mint-green thread passing through the brass eyelets of two stone blocks.

Who it's for

For companies that need to open data or operations to apps, partners or other systems.

What it solves

  • Each partner got a different integration, and keeping them all running is a job in itself.
  • A change to the API broke the app of someone already integrated.
  • The documentation is out of date, so support answers questions it should answer.
  • Errors come back as generic messages and the partner cannot tell what to fix.

What we do

Contract before code
The API described in OpenAPI and reviewed by those who will consume it, before implementation.
Resources and errors
Naming, pagination, filters and error messages that say what went wrong and how to fix it.
Versions that break nobody
A versioning policy and a notice period before retiring anything someone uses.
Authentication and permissions
Who can call what: API keys, OAuth and scopes per partner.
Usage limits
Per-client limits so that one partner cannot take the API down for everyone else.
Sandbox
A test environment with dummy data where partners can try things before going live.
Contract tests
Automated tests that flag when a change breaks what was agreed.

What you get

  • An OpenAPI specification of the API, versioned in the repository
  • The API in production, with authentication, usage limits and logs
  • Reference documentation and a getting-started guide for partners
  • A sandbox with dummy data for integration testing
  • Automated contract tests running on every change

How we do it

  1. Who consumes it

    Who will use the API, what for and at what volume.

  2. Contract

    A written specification, reviewed with your team and with a partner if there is one.

  3. Development

    Implementation that follows the contract, with tests checking every response.

  4. Sandbox and docs

    Test environment and guides published before production.

  5. Go-live

    Release to production with monitoring of errors and of usage per client.

Technology examples

  • OpenAPI
  • GraphQL
  • gRPC
  • OAuth 2.0
  • NestJS
  • Spring Boot
  • Pact

Related services

FAQ

REST, GraphQL or gRPC?

It depends on who consumes the API. For external partners, REST with OpenAPI is usually the easiest to adopt. GraphQL and gRPC come in when the case calls for them.

Do you also build the app or the website?

No. We build the API and agree the contract with your front-end or app team. See back-end for apps and front-ends.

Can you document an API that already exists?

Yes. We describe the current API in OpenAPI, point out inconsistencies and propose a new version that does not break existing users.

How do partners hear about a change?

Through the versioning policy: the change arrives in a new version, the old one keeps working for an agreed period and partners are notified in advance.

Write to Balkan

Talk to us about your project