09.05.2026 | Why your API needs a formal contract

1. What is a contract?

A contract is a document defining API capabilities and expectations. It serves as a formal agreement between the client and the server. Frontend applications consume this contract, while the server-side implements it.

Shortcut: Contract -> Interface Agreement -> Decoupled Development.

2. Contents:

  • Definition of endpoints (Paths + Methods)
  • Request parameters (Query, Payload, Headers, Cookies)
  • Responses (Status codes, Schema/Types)
  • Examples & Mock data

3. No contract specified:

Communication without contract

fig 3.1 communication without contract

The client directly depends on the server (Tight Coupling). While manageable for single teams, it creates bottlenecks between separate Frontend and Backend teams.

Drawback: Changes require manual cross-team synchronization -> High risk of breaking changes.

4. Communication based on contract:

Communication with contract

fig 4.1 communication with contract

The contract acts as the Single Source of Truth (SSoT). Teams work independently against the artifact rather than each other.

Benefit: Parallel dev -> Earlier testing via Mocks.
Drawback: "Contract Drift" -> If code changes without updating the doc, the contract becomes a lie.

5. Types of contracts:

  • User-facing (Behavior)
  • Service-to-Service
  • Unit-to-Unit
  • Data / Protocol / Operational

6. Implementation via OpenAPI (OAS):

OpenAPI Specification (OAS) is the standard for describing contracts (YAML/JSON). It is language-agnostic.

  • Swagger Editor -> Authoring tool.
  • Swagger UI -> Documentation visualization.

Drawback: Manual YAML maintenance is tedious for complex APIs -> consider Code-First vs Design-First approaches.

7. Contract Versioning

Contracts are not static. A robust versioning strategy (e.g., SemVer or URL-based) ensures updates do not break active consumers.

Shortcut: Breaking Change -> Version Increment -> Controlled Migration.

Drawback: Maintenance Debt -> Supporting legacy versions increases the testing surface and infrastructure complexity.

8. Further study

Contracts relate to "Design by Contract" (DbC) principles. Modern ecosystems leverage contracts for:

  • Static Typing: OAS -> TypeScript types via openapi-typescript.
  • Runtime Validation: OAS -> Zod / ArkTypes / JSON-Schema.
  • Type-safe Clients: Zodios / TanStack Query integration.

Well-defined specs allow both humans and LLMs to understand service relations more accurately.

Cheers,
Marcin

Komentarze

Prześlij komentarz

Popularne posty z tego bloga

23.07.2024 - A comment on comments

Comments is a part of code that is not executed during runtime. It should be short, concise and necessary. Comment shall be deemed necessary whenever there is a gap between the story that may be described by code only and actual story. It should be cherry on top that adds value by giving more insight to the logic than the naming, formating and the structure. The overriding rule regarding comments should be - keep your code understendable to yourself and future maintainers(possibly you). Do not attach comments to poorly named variables, functions and modules. Try to include as much context as possible within naming and structure. There is a common practice to set comments ide colouring to same as bacground but it is possible to overlook some valuable comment in this case. i stole the title from the book(original author Cal Evans) regards gmarcin
Czytaj więcej

15.07.2024 | simplicity

Another subject from the set of 97 things that every programer should know is simplicity. The most important thing designing software is to provide client with the functionality tailored to their real needs. Managers dont care about tools applied to obtain requested outcome as long as it gets the job done quickly and satisfy the requieements. On the other hand developers mostly need challenge and constant growth. As a consequence nowadays applications tend to be over-engineered and stuffed with additional libraries, frameworks with tons of configuration. Today ive also watched a youtube video of primagean. It was a comment on article titled "Radical simplicity". It is a reason why id written previous paragraph. The article was about technical overhead that is tend to be introduced within the aplications recently. The one good thought was that nowadays applications are able to do more stuff. The main thought was to use the bare minimum and be careful about introducing new d...
Czytaj więcej

14.04 code-smells

Yet another blog post after almost one year passed. Hello today id like to write a blog post to refresh my writing skills and think more sharply about computer science questions. "code smells" are common practices that make the code dificult to understand, maintain and extend. The root cause of smells appearing in the codbase is not uniform. It can be caused by deadlines, lack of professionalism or negligence. Nevertheless knoledge of condified code smells may lead to better understanding of the codebase. It can make you less likely to introduce one of them yourself. According to the refactoring-guru website there are six groups of code smells: "Bloaters", "OO-abusers", "Change Preventers", "Dispensables", "Couplers". bullet points about each group: bloaters - code, methods and classes of great size, oo-abusers - incomplete or incorrect aplication of oo programing principles change-preventers - one thing to change requires ...
Czytaj więcej