How to document an API for internal use

Your developer built an internal API six months ago to connect your FileMaker system with your webshop. It works fine — until that developer is on holiday, a new hire needs to build on it, or you want an external partner to pull inventory data through it. Suddenly nobody remembers which endpoint returns which fields, whether dates are in ISO format or Dutch notation, or what happens if a required field is missing. The API itself was never the problem. The missing documentation was.

This article walks through exactly what internal API documentation needs to contain, how to structure it, and which mistakes quietly cost teams the most time later.

Why does undocumented internal API matter if only your own team uses it?

"Internal only" is often used as an excuse to skip documentation, but internal APIs age the same way external ones do. A developer who wrote the endpoint for your Exact Online connector last year has moved to a different project. A new integrator joins to build a link between your CRM and your FileMaker order system, and instead of reading a spec, they open Postman and start guessing — sending test requests, reading raw JSON responses, and reverse-engineering field names by trial and error.

That reverse-engineering isn't a one-time cost. Every future integration, every bug report, every "why does this field sometimes come back empty" question repeats it. Documentation is what turns a one-person mental model into something the whole organization — including future hires and outside contractors — can rely on.

What should internal API documentation actually contain?

At minimum, working internal API documentation answers these questions for every endpoint:

1. What does this endpoint do, in one sentence? Not "GET /orders" but "Returns all open orders for a given customer, including line items and shipping status."
2. What's the exact URL and HTTP method? Include the base URL for each environment (test, staging, production) — these are almost always different, and mixing them up is one of the most common integration bugs.
3. What authentication does it require? API key, OAuth2 token, Basic Auth — state where that credential comes from and how long tokens stay valid.
4. What parameters and body fields does it accept? For each one: name, data type, whether it's required or optional, and a real example value — not just "string" but "orderDate": "2024-11-03" with the format spelled out.
5. What does a successful response look like? A full, realistic JSON example, not a schema diagram alone. Developers copy-paste example responses far more than they read field-by-field descriptions.
6. What error responses can it return, and why? A 404 because the order doesn't exist is different from a 422 because a required field was missing. List the status codes your API actually uses, with a short cause for each.
7. Are there rate limits, pagination, or size limits? If a report endpoint caps results at 500 records per call, say so before someone builds a nightly sync that silently drops data past record 500.
8. Is there a changelog? Even an internal API changes: a field gets renamed, a new required parameter appears. Without a changelog, those changes surface as production bugs instead of planned migrations.

Where should you keep internal API documentation?

There's no single correct tool, but there is a wrong pattern: documentation that lives only in one developer's head, or scattered across Slack threads and old email chains. Three approaches work well in practice, depending on your team's size and tooling:

• A dedicated API documentation tool (Swagger/OpenAPI, Postman Collections, Redoc) generates browsable, testable docs directly from a specification file. This is the strongest option once an API has more than a handful of endpoints, because the docs and the actual contract stay linked — change the spec, the docs update.
• A living page inside your internal wiki or knowledge base (Confluence, Notion, a private GitHub wiki) works well for smaller APIs or teams without dedicated API tooling. The key discipline here is ownership: assign one person per API who's responsible for keeping the page accurate.
• Inline comments plus a README in the codebase itself, for very small internal utilities. This is the minimum viable option — better than nothing, but it breaks down as soon as non-developers (a business analyst, an external contractor) need to consult it without opening the code.

Whichever you choose, the documentation needs to be reachable by everyone who might need it — including future team members who haven't joined yet. A doc buried in one person's personal Notion workspace doesn't count as documentation; it counts as a personal note.

How do you document APIs built inside FileMaker specifically?

FileMaker-based systems often expose data through the built-in Data API, through custom web publishing, or through a bespoke API layer built for a specific integration — for example, a connector that lets an external warehouse system push stock updates into a FileMaker inventory table. These APIs are easy to under-document because they were often built to solve one specific, urgent problem, with the assumption that "we'll remember how it works."

A few FileMaker-specific things worth capturing explicitly:

• Which FileMaker layout or script the endpoint actually triggers, since Data API calls typically point at a layout context that determines which fields are visible.
• Session and token handling — FileMaker Data API sessions expire, and undocumented expiry is a classic source of "it worked yesterday" bug reports.
• Any business logic hidden in scripts that fires on record creation or modification (validation, auto-numbering, related record updates) — because from the outside, the API looks like a simple database write, but internally it may trigger several dependent scripts.
• Field-level quirks: calculation fields that can't be written to directly, or fields that expect a specific value list.

Tools like Klai (an AI layer that can sit on top of FileMaker workflows) or form-building layers like FMBetterForms add another integration surface — if either is part of your stack, document how they read from or write to the underlying API, since a change in the FileMaker schema can quietly break both.

What are the most common mistakes teams make documenting internal APIs?

• Documenting the happy path only. Real integrations fail on edge cases — missing fields, duplicate records, timeouts. If your docs only show success, your team will hit every failure mode blind.
• Letting docs drift from the actual API. An endpoint gets a new required field, but nobody updates the page. Six months later someone builds against the old spec and it breaks in production. Treat documentation updates as part of the definition of "done" for any API change, not an afterthought.
• Writing for the author, not the reader. "Returns the standard order object" means nothing to someone who's never seen the standard order object. Write as if the reader has zero prior context.
• Skipping authentication details because "everyone knows how it works." New hires and outside contractors don't. Spell out exactly how to get a valid token, including where to request one if it's not self-service.
• No versioning strategy. If you change a response format, old integrations built against the previous version will silently break unless you version the endpoint (e.g. /v1/orders, /v2/orders) or clearly flag breaking changes in a changelog.

A practical checklist before you call an internal API "documented"

• Every endpoint has a plain-language description of what it does
• Base URLs are listed per environment (test, staging, production)
• Authentication method and token lifecycle are explained
• Every parameter has a name, type, required/optional flag, and example value
• A full example request and a full example response are included
• Common error codes are listed with their causes
• Rate limits, pagination, or size limits are stated explicitly
• A changelog exists and is actually updated when the API changes
• One named person or team owns keeping the documentation current
• The documentation is reachable by anyone who might need it — not locked in one person's inbox or notes

FAQ: internal API documentation

Does a purely internal API really need full documentation, or just a quick note? If more than one person will ever touch it — a colleague, a successor, an external contractor brought in for a project — it needs full documentation. "Quick notes" are fine as a starting draft, not as a permanent state.

Who should own API documentation — the developer who built it, or a separate technical writer? For most internal teams, the developer who built the endpoint should write the first draft, since they know the edge cases. But ownership for keeping it updated should be assigned explicitly, not left to whoever remembers.

Should internal API docs be public inside the company, or restricted? Generally accessible to anyone technical in the organization, including future hires. Restrict only the credentials and secrets, never the structural documentation itself — hiding docs creates the same knowledge gap you're trying to solve.

How does this connect to integrating with external systems? The same documentation discipline matters even more once an API crosses company boundaries — our broader piece on how APIs connect modern business systems covers how these connections work at a systems level, beyond documentation alone.

If your internal APIs have grown organically and nobody's quite sure anymore what each endpoint actually does, that's a common — and fixable — stage for a growing FileMaker or ERP environment to be in. Loggix can help map your existing integrations, document them properly, and where needed, build a cleaner API layer or connector so your systems, your team, and any future developer can rely on the same shared source of truth.