Document an Inherited API Before You Integrate Against It

When you inherit a platform with a large API and little documentation, the tempting move is to start building the integration and learn the API as you go. On a licensed hospital and clinic management platform, we did the opposite: we documented the whole API surface in OpenAPI first, then integrated. It was the step that made the rest reliable.

The platform and the problem

The platform covered the core of running a clinic: patient booking, lab tests, doctor scheduling, prescriptions and billing. Three kinds of software needed to talk to the same backend: the clinic backend itself, an admin panel for staff, and patient-facing apps.

Without documentation, each of those consumers would have had to work out the API independently. Each would have made its own assumptions about field names, required parameters, error formats and authentication. Differences between those assumptions are where integration bugs come from.

Why we wrote the documentation first

We produced full OpenAPI (Swagger) documentation across the platform's API surface. The OpenAPI Specification gives a standard, machine-readable way to describe every endpoint, its inputs and its responses.

Doing this before integration work has three benefits.

It forces a complete inventory

To document an endpoint, you have to call it and confirm what it really accepts and returns. That process finds the undocumented parameters, the inconsistent response shapes and the endpoints nobody knew existed, before any client code depends on them.

It becomes the contract

Once the description exists, the backend, the admin panel and the patient apps all integrate against the same written contract. When something does not match, the question is simple: does the code or the documentation need to change? Arguments about what an endpoint "should" do become one edit in one file.

It outlives the project

The next developer, internal or external, starts from a readable description instead of reverse-engineering traffic. For a platform in a regulated area like healthcare, being able to show clearly what data each endpoint handles is valuable in its own right.

Installation is part of integration

The other half of the job was environment and installation engineering for a production deployment. That covered configuring the environment properly and making the installation repeatable, so the platform could be deployed with confidence rather than by trial and error.

It belongs in the same piece of work. An API that is documented but cannot be reliably installed is not ready for anyone to integrate with. Together, the documentation and the deployment work gave the client a documented integration path between the clinic backend, the admin panel and the patient apps.

How we approach documenting an unfamiliar API

For anyone facing the same situation, this is the order we work in:

1. List the routes. Start from the framework's route list, not from memory or old notes.
2. Group by domain. Bookings, patients, scheduling, prescriptions, billing. Grouping makes gaps obvious.
3. Call every endpoint. Record real requests and responses, including errors.
4. Describe authentication once. Most integration pain starts with unclear auth.
5. Write down the surprises. Inconsistent field names or formats become known issues, not hidden traps.
6. Publish the documentation where every consumer can see it. Integration teams should never be working from different copies.

When to invest in this

Full documentation is worth the time when more than one application consumes the API, when different teams or vendors build those applications, or when the platform handles sensitive data. For a single internal script, a short README may be enough.

The anonymised write-up is in our work library. Documentation-first integration is a regular part of our product improvement work, and it pairs naturally with the checks we describe in before you build on a licensed script.