Usable API reference documentation

How can you use AI to document an API without inventing its behaviour?

1250 € per session, excl. VAT

In short

In a half-day session of 3 hours participants turn an API contract into documentation that a developer can use. AI helps structure the sections, write explanations and suggest examples, which are then checked against the sources. The work results in a documentation package accompanied by a checklist.

Why this training?

Ambiguous API documentation forces integrators to guess the parameters, errors and authentication requirements. A fluent description is not enough: every statement must match the technical contract and distinguish established behaviour from missing information. AI makes the first draft easier to write, but may add a field, an HTTP status or a rule that does not exist. The training teaches participants to constrain its suggestions using the sources, then check their accuracy before including them in the documentation package. Running case study: The fictitious organisation Sovrane Consignes provides an API for booking lockers. A partner needs to check availability, create a booking and cancel it. The supplied package includes three operations, their JSON schemas, the authentication rules and simulated responses, but no documentation for integrators. Transfer to the workplace: Within the following two weeks, apply the template to an authorised real-world operation, have a developer review the examples and measure section coverage and deviations from the contract. Record the corrections before any publication.

Objectives of this training

• Extract information that can be documented from an API contract.
• Structure a reference for each operation and a first-use guide.
• Use AI to write descriptions and examples that are traceable to the sources.
• Check the consistency of the documented requests, responses and errors.
• Measure documentation coverage and identify information that needs confirmation.

Who is it for and what are the prerequisites?

Roles and tasks concerned

• Developers responsible for making an API accessible to integrators.
• Technical writers and product managers involved in interface documentation.

Prior skills

• Understand HTTP methods, status codes and JSON structure.
• Have previously used a generative AI assistant for a writing task.

What you will work on

1. Analyse the contract and its limitations

   Objective: Define what can be documented without assumptions. Reference sources, operations, schemas, authentication and the distinction between missing information and missing functionality.

2. Write the operation reference documentation

   Objective: Produce consistent, verifiable sections. Descriptions, required or optional parameters, value constraints, HTTP statuses and error messages.

3. Build the integration workflow

   Objective: Link the operations in a first-use guide. Fictitious URL, placeholder token, JSON examples, call sequence and handling of known errors.

4. Evaluate and prepare for maintenance

   Objective: Assess the quality of the package objectively before publication. Documentation coverage, terminological consistency, traceability of corrections and update triggers.

What you take away

• Matrix of sources, sections and missing information.
• Reference documentation for the three operations.
• Guide to making a first booking, with example requests and responses.
• Completed checklist and correction log.

Method and assessment

• Short instructional inputs followed by immediate practice on the running case study.
• Individual work followed by work in pairs, with reciprocal review of the outputs.
• Facilitated group review: what works, what needs correcting and what remains a human decision.
• Preparation: Have access to an AI assistant and a text editor approved by the organisation. Prepare an anonymised contract extract containing no secrets; a wholly fictitious package is provided for the exercises.

Observable criteria: The three operations specify the method, path, parameters, body where applicable, responses and known errors. ; Every documented rule refers to a source; unknown elements remain explicitly flagged. ; The examples comply with the types, required fields and statuses in the supplied contract. ; The guide enables a peer to reconstruct the workflow without a verbal explanation. ; Coverage is calculated as the ratio of complete sections to expected sections..

Frequently asked questions

Do you need access to an API?

No. The contract and simulated responses enable documentation checks; they do not replace integration tests.

Can you send tokens to AI?

No. The examples use placeholder values, with no real identifiers or personal data.

Is the documentation published during the session?

No. The package still needs to be validated through the organisation’s technical approval process.

What should you do if the contract is incomplete?

Identify the gap precisely and consult the person responsible for the API rather than letting AI invent an answer.