Case study: set up an API documentation set
Guidance for developers on setting up APIs on a government platform. It covers repositories, configuration, secrets, monitoring, and readiness. Built in VS Code, peer reviewed in GitHub and written in Markdown.
About the pages linked below. They are adapted from the documentation I wrote. Platform and team names, infrastructure details, repository names and internal references have been removed or replaced. The structure, the writing and the approach are as I wrote them.
Problem
Onboarding steps were fragmented across tools and hard to scan.
What I did
Created task based guidance pages to help developers set up APIs for microservices.
Impact
Clear next steps, fewer support questions, and consistent patterns across the documentation set.
Browse by category
Jump straight to guidance grouped by lifecycle stage.
Getting started
- Prepare to build an APIStandards and approvals to line up before you write code
- Create a repository for your APIScaffold a repository with the platform's template files
Configuration and security
- Create app configurationSet base and per environment settings for your service
- Encrypt an application secretEncrypt credentials before they go into configuration
Integration and service management
- Add your service to the service managerLet other teams run your service in their local setup
Monitoring and alerting
- Add a logs dashboardSee the requests and errors that matter for your service
- Add a metrics dashboardTrack request rates, response times and error rates
- Set up alerting for your teamCreate accounts for everyone who will be on call
- Add alerts for your serviceChoose what triggers an alert and who it reaches
Readiness and compliance
- Create a platform readiness assessmentMeet the readiness criteria before your service goes live
Set up an API documentation set
This guidance is for teams setting up an API on the platform. Follow the sections below to configure everything from repositories to monitoring and readiness.
Preparation
Prepare to build an API
Get the standards and approvals lined up before you write any code.
Repository and configuration
Create a repository for your API
Scaffold a repository from the platform template.
Create app configuration
Define base and environment configuration for your service.
Encrypt an application secret
Encrypt credentials and API keys before they go into configuration.
Service management
Add your service to the service manager
Let other teams run your service as part of their local setup.
Observability
Add a logs dashboard
See the queries and errors that matter for your service.
Add a metrics dashboard
Track request rates, response times and error rates.
Readiness
Create a platform readiness assessment
Make sure your API meets the readiness criteria before it goes live.