Every field you name is a promise the client's ERP will keep
Decide who may call the API, choose REST or GraphQL by the caller, and write the contract before the code, because endpoints outlive models.
In brief
- To a client's systems, an API is a contract. Write the contract (OpenAPI or a GraphQL schema) before you write code.
- Do not let the API mirror the database. Name resources after business nouns, and make any write that might be retried idempotent.
- Adding a field rarely breaks clients. When a breaking change is unavoidable, pick a versioning strategy and spell it out in the handoff documentation.
Three weeks into a client engagement, the shipment-risk model is running and the demo has gone smoothly. Then the client’s ERP lead asks three questions: where does their system call, what data comes back, and how will they be told when your side changes?
Those three questions decide what happens to the solution after you leave. The model can be swapped for another one. The endpoints the ERP team has written code against are much harder to change.
Your job is to design that API layer so the client’s team can integrate with it, run it and upgrade it themselves without calling you back.
An API is a contract, not a technical detail
IBM defines an API as a contract that lets one piece of software access data or invoke functions provided by another. For an FDE, the word “contract” should be taken literally. Every field in a response is a commitment, and the team on the other side will build business logic on it.
So the first question to settle is who is allowed to call the API. REST versus GraphQL comes later. IBM classifies APIs by access level: public APIs are fully open to the internet, while partner and private APIs restrict who can use them.
A risk-scoring solution that serves only an internal ERP and a few shipping partners almost certainly does not need to be public. Getting this right at the start spares you a good many meetings with the security team later.
REST or GraphQL: choose by the caller
According to IBM, REST is the most popular architecture for web APIs today, while SOAP is an XML-based messaging protocol with strict standards for message structure and transport. If the client’s ERP speaks only SOAP, you work with SOAP. For a new design, the realistic choice is usually REST or GraphQL.
GraphQL’s official documentation describes it as a way to build flexible, version-free APIs on a strong type system. The schema defines the shape of the data, and clients request exactly the fields they need.
One detail is easy to miss: the GraphQL specification deliberately leaves networking, authorization and pagination undefined, so your team has to design all three.
REST
- The most popular architecture for web APIs; the ERP team almost certainly knows it
- Resources are named as nouns; behavior follows the HTTP method
- Breaking changes are handled with versions: URI, query string, header or media type
GraphQL
- Clients fetch exactly the fields they need, which suits many screens with different data needs
- The schema evolves over time instead of being versioned
- Authorization, pagination and networking must be designed by you, because the spec does not define them
For an ERP integration team that needs only a few fixed operations, REST is usually the lower-risk choice at handoff. GraphQL makes more sense when the main consumers are several frontends, each needing a different slice of the data.
A worked example: a shipment-risk API
Take the logistics client from the opening, a hypothetical case. The team’s first draft typically looks like this: an endpoint POST /getRiskScore returning {"shp_id": 8812, "rsk_v2": 0.83, "flg_manual": 1}. It works, but it contains three mistakes that will cause trouble after handoff.
The first is a verb in the URI. Microsoft’s guidance recommends naming URIs after nouns (the resources) rather than verbs (the operations on them).
The second is that rsk_v2 and flg_manual come straight from column names in the table. Microsoft advises against designing an API that mirrors the internal structure of the database. The day you rename a column, every client breaks with it.
The third is the hardest to spot. The ERP sends shipment data, hits a timeout and retries automatically. If the write endpoint uses POST, each retry can create another record.
Microsoft notes that PUT must be idempotent: sending the same request several times still modifies exactly one resource with the same values. POST and PATCH carry no such guarantee.
The revised version is written as a contract before any code. Microsoft calls this contract-first: design the contract, meaning the interface, and only then write the code that implements it. The first part of the contract declares the write operation:
openapi: 3.0.3
info:
title: Shipment Risk API
version: 1.0.0
paths:
/v1/shipments/{shipmentId}:
put:
summary: Create or update a shipment (idempotent, safe to retry)
The next part, under the same paths section, describes the read operation and the response shape the ERP will receive:
/v1/shipments/{shipmentId}/risk-assessment:
get:
summary: Get the latest risk assessment
responses:
'200':
content:
application/json:
schema:
type: object
required: [shipmentId, riskLevel, score]
properties:
shipmentId: { type: string }
riskLevel: { type: string, enum: [low, medium, high] }
score: { type: number, minimum: 0, maximum: 1 }
reasons: { type: array, items: { type: string } }
Look at what has changed. The resources are now shipments and risk-assessment, nouns anyone on the ERP side understands at once. Writes use PUT keyed on a shipmentId supplied by the ERP, so however many retries occur, there is only one shipment.
Internally, a mapping layer translates rsk_v2 into score, so you can change the database schema while the contract stays the same.
When do you need a version?
Six months later, the client wants a new field, estimatedDelayHours. Adding a field usually does not break clients, because old code simply ignores fields it does not know. Changing riskLevel from a string to a number, or removing reasons, is a breaking change.
For breaking changes, Microsoft lists four strategies: a version in the URI, in the query string, in a header, or in the media type. Microsoft rates URI versioning such as /v1/ as the simple option, but warns that it becomes unwieldy as the API goes through many rounds of change and the server has to maintain several versions at once.
GraphQL takes a different route: the type system evolves over time without versions. In practice, you add the new field, keep the old one, and remove the old one only once you are sure no client still uses it.
Whichever you choose, write the rule into the handoff documentation so the client’s team knows when a field will be removed and how they will be warned in advance.
A process for the next project
Start by listing the business nouns the client uses in conversation, such as shipment, order, assessment; these are candidate resources. Then, for each write operation, ask the integration team whether their client retries on timeout.
If it does, design that operation as a PUT on a client-supplied ID. When you have to keep POST, the common approach is to require the client to send an idempotency key in a header, so the server can recognize a repeated request and return the earlier result instead of creating a new record.
Next, write the OpenAPI contract or GraphQL schema and review it with the people who will actually call the API. If you chose GraphQL, bring authorization and pagination into that review, because the specification will not handle them for you. Only once both sides agree should you write the mapping layer and the handling code.
The most common mistakes all come from shortcuts taken for speed: returning ORM entities directly in responses, using POST for every write, changing a field’s type without bumping the version, making an API public when partner access would do, and choosing GraphQL on the assumption that it comes with authorization built in.
Each one saves an afternoon while coding and costs the client weeks after handoff.
Showing this skill in a job search
When reading an FDE job description, look for phrases such as “integration”, “API design” or “customer-facing technical delivery”. They signal that the role will use exactly this skill.
On your CV, instead of writing “built REST APIs”, be specific: wrote contract-first OpenAPI specs, reviewed them with the partner’s integration team, and designed idempotent write endpoints so clients could retry safely.
Before the interview, prepare an answer to a scenario like this: the client needs to change a field that several systems call into; what do you do? A convincing answer starts with a contract that was written down on day one.
Was this article useful?
Thanks for the feedback!