What Should an API Contract Include Before Development Starts?

When two pieces of software need to talk, such as your website and your ERP, or your mobile app and its backend, someone has to agree exactly how. Get that wrong and you find out late: the app team built screens for data the backend doesn’t send, or a partner’s integration breaks on day one. So what is an API contract? It’s the written, precise agreement on how an API will behave, made before anyone writes the code.

This guide explains what an API contract should include, shows a small example, and gives you a checklist to review one even if you’re not a developer. If you need an API designed and built this way, our custom API development page explains how we start every backend project with a signed-off contract.

Quick answer: An API contract is a technical specification, usually written in the OpenAPI format for REST APIs, that lists every endpoint, the data each one accepts and returns, how users and systems authenticate, what errors look like and the rules around limits and versions. Approving it before development lets web, app and partner teams build in parallel and makes scope, cost and testing far clearer.

What is an API contract, in plain terms?

Think of an API as a counter at a shop. Customers (your website, app or partners) ask for things; the shop (your backend) hands them over or says no. The API contract is the menu and the house rules: what you can ask for, how to ask, what you get back, and what happens if you ask for something you’re not allowed.

It’s called a contract because both sides rely on it. The backend team promises to deliver exactly what’s described. The front-end, app and partner teams promise to ask only in the ways described. As long as both sides stick to it, they can work at the same time without waiting for each other.

Contract-first vs code-first

• Code-first: developers build the API, then write documentation describing what they built. Other teams wait, then discover mismatches.
• Contract-first: the team writes and agrees the contract, then builds to it. App and web teams can start immediately against a mock server that returns sample responses.

For anything beyond a tiny integration, contract-first is usually cheaper, because disagreements are settled on paper instead of in code.

What an API contract should include

Section	What it answers	Who should check it
Overview and scope	What is this API for? What’s out of scope?	You, the business owner
Endpoints (or GraphQL operations)	What can be requested or changed?	Web, app and partner teams
Request and response shapes	Which fields, types and formats?	Developers on both sides
Authentication	How does a user, app or partner prove who they are?	Developers, security reviewer
Permissions	Who may see or change each kind of data?	You, plus developers
Errors	What does a failure look like, and what should the caller do?	Developers on both sides
Pagination, filtering and sorting	How are long lists handled?	Front-end and app teams
Rate limits	How many requests are allowed, and what happens over the limit?	Partners, operations
Webhooks and events	What does the API notify others about?	Integrating systems
Versioning and change policy	How will changes be introduced without breaking apps?	Everyone
Non-functional needs	Response time, uptime expectations, data retention	You, operations
Examples	Real sample requests and responses	Everyone

Endpoints and data shapes

Each endpoint should state its address, method (for example, GET to read, POST to create), the fields it accepts, which are required, their types and formats (dates, currency, phone numbers), and exactly what comes back. Agree formats early: is a price “1499” in paise or “14.99” in rupees? Is a date in UTC? These small choices cause big bugs.

Authentication and permissions

State how callers sign in (for example, OAuth 2.0 for user logins, or API keys or tokens for partner systems) and, more importantly for you, who may do what. A warehouse user might update stock but not see customer addresses; a partner might read product data but not prices. This is the section business owners should read most carefully.

Errors

Good contracts define a consistent error format with a code, a human-readable message and, where useful, which field caused the problem. They also say what the caller should do: retry later, fix the input or contact support. “Something went wrong” is not an error design.

Webhooks and background events

If your API tells other systems when something happens, such as a payment clearing or an order shipping, the contract should describe each event, its data, how it’s signed so receivers can trust it, and how retries work if the receiver is down.

Versioning and change policy

Software changes. The contract should say how new fields are added, how breaking changes are introduced (usually as a new version), and how much notice partners get before an old version is retired.

A tiny example in OpenAPI

Most REST API contracts today are written in the OpenAPI Specification, a standard, machine-readable format. Tools can turn it into interactive documentation, generate mock servers and test that the finished API matches. A very small excerpt looks like this:

paths:
  /orders/{orderId}:
    get:
      summary: Get one order
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
        "404":
          description: No order with this ID, or not visible to this user

You don’t need to read YAML to review a contract. Ask your developer for the interactive documentation generated from it, and click through the endpoints with them.

What a contract does for cost and timeline

A signed-off contract is also the clearest scope document you’ll have. Each endpoint, integration and permission rule is listed, so a fixed quote can be priced against something concrete rather than a paragraph of intentions. During the build, weekly demos can show real calls working against the agreed contract, and at hand-over the finished API can be tested against it line by line. When someone later asks for “just one more field”, everyone can see it’s a change, decide whether it’s worth it and record the cost. That shared reference is what stops a backend project from drifting.

How to review a contract if you’re not a developer

1. Walk through a real scenario. “A customer orders two items, pays by UPI, then cancels one.” Ask the developer to show which calls happen at each step.
2. Check the awkward cases. Part-payments, refunds, duplicate orders, out-of-stock items, a partner system that’s offline.
3. Read the permissions table line by line. Ask “who can see this?” for every sensitive field.
4. Check names match your business language. If your team says “job” and the API says “ticket”, decide now.
5. Confirm what’s out of scope. It’s as important as what’s in.
6. Ask what happens when it changes. Who approves changes, and how are costs handled?

Mistakes to avoid

• Starting to code from a short brief. Mismatches are cheapest to fix on paper.
• Leaving errors and edge cases for later. That’s where integrations fail in production.
• Hiding permissions in the code only. Write them in the contract so they can be reviewed and tested.
• Ignoring third-party limits. Your ERP or gateway’s own rate limits and licence rules shape your contract.
• No examples. Sample requests and responses remove most ambiguity.
• No versioning plan. The first change will otherwise break someone’s app.

Pre-development checklist

• Every system and data flow listed, with who triggers what
• All endpoints or GraphQL operations described with fields and formats
• Authentication method agreed for users, apps and partners
• Permissions written for each role and sensitive field
• Consistent error format, with what callers should do
• Pagination, filters and rate limits defined
• Webhooks, signatures and retries described
• Versioning and change policy agreed
• Example requests and responses for every endpoint
• Mock server or interactive docs shared with every team
• Contract approved in writing before development

How Omebly can help

Omebly designs and builds APIs and backends for websites, web apps and mobile apps, working remotely from Kolkata and Downtown Dubai with calls in your time zone. Every project starts with integration mapping and a written OpenAPI contract that you approve before we build, followed by weekly demos with real test calls, Swagger-style documentation and a Postman collection at hand-over.

Our custom API development services cover REST and GraphQL endpoints, OAuth 2.0 or token authentication, payment and ERP integrations, webhooks and monitoring. If you need the screens and users as well, our web app development work includes an API like this as part of the build; both sit under our web development service. For a broader view of how APIs fit into a product, read our guide to web app vs website.

Have systems that don’t talk to each other? Describe them to us and we’ll sketch the contract with you.