Shall, Will, and API Contract Language

By the end of this lesson, you will be able to...

• Use will to state committed API behavior.

• Recognize shall as formal contract language and choose a clearer alternative when needed.

• Separate future plans, system promises, and normative requirements in short API sentences.

Idea in one sentence: In API language, will usually says what the system promises to do, while shall sounds like formal rule language and needs careful handling.

Core Insight

Lesson 014 used may for permission:

Clients may send one optional filter.

Lesson 015 used would for a hypothetical result:

Routing 10% of exports first would reduce rollback risk.

Now the API behavior is no longer hypothetical. The team has decided what the server does when a client repeats a request.

The central practice line is:

The server will return 409 for duplicate requests.

This is contract-style English. It tells the reader what behavior to expect.

The small danger is that will and shall both sound strong, but they do not feel the same to a technical reader.

Will is usually natural for a system promise:

The server will return 409 for duplicate requests.

Shall is more formal:

The server shall return 409 for duplicate requests.

That second sentence may appear in specifications, standards, or contract documents. In normal API docs, it can sound legal, old-fashioned, or heavier than needed.

The lesson is not "never use shall." The lesson is: know what kind of commitment the sentence is making.

The Small Situation

Imagine the export API from the previous lessons:

POST /exports

Clients send an idempotency_key so a retry does not create two export jobs.

The team has agreed on this behavior:

If a client repeats the same request with the same idempotency key,
the server returns HTTP 409 Conflict.

Now someone has to write the public API sentence.

A naive version is:

The server shall return 409 for duplicate requests.

This may be grammatically correct. It also sounds formal. Depending on the document, that may be fine or too heavy.

For most API docs, a clearer version is:

The server will return 409 for duplicate requests.

The reader does not need to wonder whether this is legal language, future planning, or old-style specification language. The sentence says what the server promises to do.

Three Kinds of Strong Sentence

Use this small table before choosing the modal.

The difference is not only grammar. It is reader expectation.

Will points to behavior:

The server will return 409.

The reader asks:

What happens when I call the API?

Must points to requirement:

Clients must include an idempotency key.

The reader asks:

What am I required to send?

Shall points to formal obligation:

The client shall include an idempotency key.

The reader may ask:

Is this a legal contract, a standard, or just normal docs?

That extra question is the cost.

Plain to Precise Bridge

Plain meaning:

Will says, "this is the behavior you should expect."

In this scenario:

If you send a duplicate export request, the API response is predictable.

Technical sentence:

The server will return 409 for duplicate requests.

Plain meaning:

Shall says, "this is a formal rule or obligation."

In this scenario:

If the document is a strict protocol specification, shall may be used to mark required behavior. But many modern technical teams prefer must for requirements and will for server behavior.

Technical sentence:

The server shall return 409 for duplicate requests.

Read that sentence as formal specification style, not casual future English.

A Worked API Contract Trace

Here is the tiny contract.

Endpoint: POST /exports

Client requirement:
- The client must include an idempotency_key.

Server behavior:
- The server will create one export job for a new key.
- The server will return 409 for a duplicate request.

Permission:
- Clients may send one optional date filter.

Now trace three requests.

The modal changes with the owner of the sentence.

For the client:

Clients must include an idempotency key.

The client controls the input. This is a requirement.

For the server:

The server will return 409 for duplicate requests.

The server controls the response. This is committed behavior.

For the optional filter:

Clients may send one optional date filter.

The client is allowed to send it, but not required.

The naive failure is to use one strong modal everywhere:

Clients shall include an idempotency key.
The server shall return 409.
Clients shall send one optional date filter.

The first two sentences may work in a very formal specification. The third sentence is wrong for the intended meaning, because shall send makes the optional filter sound required.

The better contract separates the jobs:

Clients must include an idempotency key.
The server will return 409 for duplicate requests.
Clients may send one optional date filter.

So far, the ladder is:

may = allowed
must = required
will = promised system behavior
shall = formal rule language; use only when the document style expects it

Evidence Before Commitment

Before you write will, check whether the team has enough evidence to make that promise.

Suppose the pull request has only this note:

We think duplicate requests should probably return 409.

That is not contract language yet. It is a design intention. The implementation may not be merged. The tests may not exist. The old endpoint may still return 200 for a repeated request.

At that stage, use a softer sentence:

The endpoint should return 409 for duplicate requests.

Now the sentence sounds like a requirement or recommendation that still needs verification.

After the behavior is implemented, tested, and documented, the sentence can become:

The server will return 409 for duplicate requests.

The modal changed because the evidence changed.

Here is the small path:

The trade-off is precision versus premature certainty. Will is clear when the behavior is truly promised. It is risky when the team is still deciding or testing.

If you are not sure, ask one practical question:

Can a client rely on this sentence today?

If the answer is yes, will may fit. If the answer is no, use should, must, or a design note until the commitment is real.

When Shall Fits

Shall still appears in technical standards, procurement contracts, regulated environments, and older specifications.

It can fit when the document has an explicit style rule like this:

In this specification, "shall" means a mandatory requirement.

In that kind of document, shall is not decorative. It has a defined job.

But in everyday engineering writing, shall often creates avoidable friction.

Compare:

The API shall reject requests without an idempotency key.
The API must reject requests without an idempotency key.

Both are strong. The must version is usually easier for a broad engineering audience. It reads like a requirement, not a legal clause.

Now compare:

The server shall return 409 for duplicate requests.
The server will return 409 for duplicate requests.

If the reader is an API consumer, the will version is usually more natural. It answers the consumer's question: what response will I get?

Common Confusions

Confusion: will always means a future plan

Why it is tempting:

Many English lessons teach will as the future.

Better model:

In API docs, will often describes committed behavior, not a plan that might happen later.

The server will return 409 for duplicate requests.

This means the behavior is part of the contract now.

Confusion: shall is just a stronger will

Why it is tempting:

Both words can sound formal or certain.

Better model:

Will is good for behavior the system promises. Shall is formal rule language. If the document does not define shall, the word may add weight without adding clarity.

Confusion: every contract sentence needs the same modal

Why it is tempting:

A contract feels like one document, so one modal feels tidy.

Better model:

Different sentences have different owners. Client requirements, server behavior, permission, and prohibition need different modals.

Clients must include an idempotency key.
The server will return 409 for duplicate requests.
Clients may send one optional filter.
Clients must not send private tokens.

The variety is not messy. It is precise.

Trade-offs and Limits

Using will for server behavior improves readability. It makes API docs feel direct and practical.

It also has a cost. Will can sound too much like prediction if the sentence is about a requirement instead of behavior.

Weak requirement:

Clients will include an idempotency key.

That sounds like a prediction about what clients do. It is not strong enough as a requirement.

Clearer:

Clients must include an idempotency key.

Using shall can make a document feel formal and enforceable. That may be useful in a standard or regulated contract.

It also has a cost. It can make normal product docs feel legalistic. It can also hide the difference between required client input and promised server behavior.

You can see the boundary when a reader asks:

Is this a legal requirement, or just what the API does?

That question is a signal. The modal is carrying too much ambiguity.

Check Your Understanding

Check: Which sentence best states committed server behavior in normal API docs?

A. The server will return 409 for duplicate requests.
B. The server may return 409 for duplicate requests when it feels appropriate.
C. Clients shall maybe send one optional filter.

Think first, then reveal.

Answer: A is best. Will states the server behavior directly. May sounds optional or permitted, and shall maybe mixes formal obligation with uncertainty.

Check: Which sentence is the clearest requirement for client input?

A. Clients will include an idempotency key.
B. Clients must include an idempotency key.
C. Clients would include an idempotency key if the migration were polite.

Think first, then reveal.

Answer: B is best. The client is required to send the key, so must is clearer than will. Will sounds like prediction, not requirement.

Practice

Rewrite each rough line.

Now write three API lines for this endpoint:

POST /exports
required: idempotency_key
optional: date_from
duplicate request: 409 Conflict

Model answer:

Clients must include an idempotency key.
Clients may send one optional date filter.
The server will return 409 for duplicate requests.

The three sentences do not use the same modal because they do not do the same job. That is the main habit to build: choose the modal after you identify the job of the sentence.

Daily Practice Lines

Read these lines once or twice during the day:

The server will return 409 for duplicate requests.
Clients may send one optional filter.
Would you review the migration plan?

The first line is new.

The second line reviews permission from lesson 014.

The third line reviews polite collaboration from lesson 015.

Resources

• [REFERENCE] RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
  • Link: https://www.rfc-editor.org/rfc/rfc2119
  • Focus: Notice how formal specifications define requirement words instead of relying on ordinary grammar alone.
• [REFERENCE] RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
  • Link: https://www.rfc-editor.org/rfc/rfc8174
  • Focus: Use it to see why requirement words need an explicit convention in formal documents.
• [ARTICLE] Cambridge Dictionary Grammar: Will
  • Link: https://dictionary.cambridge.org/grammar/british-grammar/will
  • Focus: Compare ordinary future uses with the stronger commitment you see in API examples.
• [ARTICLE] Microsoft Writing Style Guide
  • Link: https://learn.microsoft.com/en-us/style-guide/welcome/
  • Focus: Use it as a practical reference for clear, reader-friendly technical wording.

Key Takeaways

• Use will for committed API behavior: The server will return 409 for duplicate requests.
• Use must for clear client requirements: Clients must include an idempotency key.
• Treat shall as formal rule language. Use it only when the document style expects it or defines it.
• Do not force one modal across the whole contract. Match the modal to the owner: client, server, permission, or prohibition.