API Documentation

Cloud Workload Automation API Ecosystem

Randstad (deputed to Accenture) · May 2023 – Sep 2024

40+ endpoints · Python SDK · 40% fewer integration defects.

My role

Sole documentation owner for the API surface, working directly with the platform engineers who owned the SAP and Docker integration paths.

REST APIs · OpenAPI · Swagger · Python SDK · SAP Webhooks · Docker · Docs-as-Code

Problem: 40+ REST endpoints and a Python SDK to document in a four-week sprint, with third-party integrations nobody had written down.
Insight: Most of the configuration knowledge for the SAP and Docker paths lived in two engineers' heads. That is where customers were getting stuck, and it was the part nothing had been written about.
Result: A complete reference set delivered inside the sprint, with third-party pipeline configuration defects down 40%.

The full story

A workload automation platform is mostly reached through something else: a SAP webhook, a container, a Python SDK. The endpoints themselves are conventional. The scope was 40+ REST endpoints plus the SDK guides, inside a four-week sprint, against a surface engineering was still adding to.

The approach was spec-first and Docs-as-Code throughout. The OpenAPI description, maintained in Swagger, became the source the reference was generated from, so the published documentation could not drift from the contract as endpoints landed. That decision is what made a four-week sprint survivable: new endpoints arrived as spec changes, not as writing tasks.

The numbers came from the integration work. Sitting with the engineers who owned the SAP webhook and Docker paths turned up configuration steps nobody had written down, including two that were only known because a customer had hit them. Documenting those cut third-party pipeline configuration defects by 40%.

AI-assisted prompting took the mechanical load: reading raw code and turning schema parameters into first-draft prose. That work eats a sprint and rewards very little judgment. Everything it produced was checked against the source before it shipped, which is the condition that makes the speed worth having. We held 100% data integrity.

Key decisions

Generate the reference from the OpenAPI description instead of maintaining prose beside it. In a sprint where endpoints were still landing, hand-maintained reference would have been wrong before it was published.
Document the integration seams before the endpoints. The endpoints were self-similar and largely inferable; the SAP and Docker configuration paths were neither, and that is where the defect rate actually lived.
Use AI-assisted prompting for schema parameter translation and code parsing, then check every line against the source. The speed is real and it is worth nothing without the check. Unverified generated reference is confidently wrong in exactly the places a reviewer is least likely to look.

What it taught me

I would sequence this differently if I did it again. Endpoints came first because they were the visible deliverable and the sprint was short, so the SAP and Docker paths did not get written until week three. The defect numbers say those were the pages worth the time. Next ecosystem, I start at the integration boundary and work inward.