Handing our API docs to a developer or agency: section links, Markdown and the specification

The short answer: you do not need to explain the API to whoever is programming. Just send the right links: the start page, the area that matters, the rules and the specification. And a key just for them, if they need to test, never your own.

What to send, depending on the job

For	What to send
Getting started	The home page and Get started with the API.
A specific task	The area page, or the direct link to the operation.
An integration that does not break	The API rules.
Importing into their tools	The OpenAPI specification, at the end of the reference.
Working with an AI assistant	The llms.txt file and the Markdown versions of the pages.

Linking to a section or an operation

Next to every section heading there is a link symbol: one click copies the address of that section and you see "Link copied". Operations have the same symbol, and whoever opens the link lands with the operation already open. So instead of "see the bit about limits", you send the exact spot.

The key: one for them, never yours

1	Create a separate key for the developer, in My MozOut, on the API page, with a name that identifies them.

2	Start in Sandbox: it reads real data, but writes are simulated and nothing is charged.

3	Give only the permissions the job needs, and a short validity.

4	When the job is done, revoke it. To put the system into real use, create a prod_ key with the minimum permissions.

Never send your production key by email or message. If a key has been somewhere it should not, revoke it and create another: what to do, in the right order.

In the language of whoever is programming

If the developer prefers Portuguese, send the links to the Portuguese version, which has the same content: see where each language lives.

Agree on two rules from the start: the key lives in an environment variable, outside the code, and every reported problem includes the X-Correlation-ID from the response. It saves days of back and forth.

Start by sending the documentation home page.

Open the documentation

Categories

Categories