WeXL Forge · Design · Live

Forge API

Writes OpenAPI contracts and mocks so no team waits on another

Takes
User stories with acceptance criteria (.md, Jira CSV)Your API style guide or existing OpenAPI files
Gives
OpenAPI 3 contract (YAML)Example requests and responsesA mock server configurationOpen questions for the API owner
Updated
Draft

The problem

On any project with more than one team, someone is always waiting. The mobile app needs the accounts endpoint; the accounts team needs the core banking adapter; the adapter team is waiting on the upstream system’s test environment. Contract-first API design is the known answer: agree the request and response shapes first, publish a mock, and let everyone build against it. In practice the contract is the job nobody has time for. It gets written late, by hand, by whichever backend developer is free, and it is often missing the error cases, the paging rules and the field formats the consuming team needed most.

Where it breaks is the gap between the stories and the contract. A story says “the user sees their last 50 transactions, newest first”. The contract says GET /transactions with no limit, no sort order and no mention of what happens when the account is closed. Two teams read it differently, both build to their reading, and the mismatch turns up in integration testing, weeks later.

Good looks like this: every endpoint traces to a story that needs it; the contract follows the house API standards for naming, versioning, errors and paging; there are realistic example payloads for the happy path and the failure cases; a mock is running the same day; and the questions the stories did not answer are put to the API owner before anyone writes code.

How it works

Forge API reads a set of user stories with their acceptance criteria. These can be written by hand or come from Forge Spec. It also reads your API standards: a style guide, existing OpenAPI files from neighbouring services, or both. Those standards steer every choice it makes about naming, error format, paging and versioning.

It drafts an OpenAPI 3 contract: the resources and endpoints the stories need, request and response schemas, status codes and error bodies, and example payloads for both success and failure. Each operation records which story and acceptance criterion it serves. Anything the stories imply but do not settle (a maximum page size, whether a field can be null, who is allowed to call the endpoint) goes into a list of open questions instead of being guessed into the schema.

Then it is checked. The contract must be valid OpenAPI, and it is linted against your API rules. An endpoint with no story behind it is flagged. From the checked contract it produces a mock configuration, so the consuming teams can start building against realistic responses while the real service is still being written.

A person then reviews it. In practice that is the API owner on the providing team, with a lead from the consuming team, and the contract is agreed between them before either side builds. After that, the contract is the shared source of truth, and changes go through review like code.

This is the way of working used on the delivery for a leading Southeast Asian bank, delivered with a leading consulting firm: where upstream systems were not ready, squads built against agreed contracts with mocks, so no one sat idle. Forge API is that practice, packaged so it starts on day one.

Where it gets it wrong

Forge API is good at turning stories into a consistent first contract. It cannot know your systems the way your architects do, and it fails in predictable ways.

  • It models the story, not the system. If the stories describe a screen, the draft contract can mirror the screen too closely, one endpoint per view, instead of the resources your domain actually has. The API owner’s review is where that gets reshaped, and the open questions often point at it.
  • It does not know the upstream system. Field lengths, code lists and odd formats in a core system are rarely in the stories. Unless an existing contract or schema is supplied, those fields are drafted generically and flagged.
  • It can over-specify. A draft may add fields or filters that seem sensible but no story asked for. Because every operation carries its story reference, anything without one stands out.
  • Security is a decision, not a draft. It will mark which endpoints need authentication and suggest scopes, but who may see what is a decision for your security architects. It is raised as a question, never settled silently.

A mock built on a wrong contract is worse than no mock, because two teams build the same mistake. That is why the contract is agreed by people before the mock is shared.

Why not just prompt a chatbot

A chatbot will write an OpenAPI file from a paragraph of description, and it will look complete. It will not follow your error format, your naming rules or your paging convention, and it will not tell you which endpoint came from which story or what it made up. What makes Forge API useful is the steering from your own API standards, the trace from every operation back to a story, the lint and validation that run before anyone sees it, and the mock that comes out of the same checked file. That is the work, and it is what you keep.

What you get

  • In your engagement: Forge API drafts contracts and mocks from your stories in the first sprint, so front-end and back-end teams start in parallel.
  • Under your brand: services firms can run it inside their own delivery platform, steered by each client’s API standards.
  • Built to own: we fit it to your API style guide, gateway and mock tooling, and hand over the source.

See three ways to use an agent.

Run it on your input.

Send us a real set of user stories. We run Forge API on it and send the output back within one working day, with a note on what we would change for your setup.

Start here

See Forge on your own codebase.

Start a conversationWe'll show the Live agents on a real workflow of yours.