Browse by category
Jump straight to guidance grouped by lifecycle stage.
Getting started
- Design an API
Overview of the steps to design, specify, and document an API microservice.
- Prepare to build an API
Standards and approvals to line up before you write code
- Research and document an Alpha API
Steps for teams documenting an API during its Alpha phase.
- Research and document an API
Plan the documentation journey before delivery.
- Create a repository for your API
Scaffold a repository with the platform's template files
API specification
- Write the OpenAPI specification (OAS)
Define your API using OAS 3.0.3 — info section, security schemes, and paths.
- Update the API overview
Keep the overview clear, accurate, and up to date.
- Create an end-to-end service guide or roadmap
Create connected documentation for planning and delivery.
Access and authorisation
- Manage API authorisations and access
Overview of the access control guides to follow before managing API access.
- Set up API access scopes
Define and manage OAuth scopes for user-restricted and privileged applications.
- Assign access levels to an API endpoint
Add application-restricted or user-restricted security to each endpoint in your OAS.
Configuration and security
- Create app configuration
Set base and per environment settings for your service
- Encrypt an application secret
Encrypt credentials before they go into configuration
- Generate testing credentials
Generate credentials to authenticate API requests during testing.
Documentation validation
- Preview API documentation locally
Validate rendered documentation before publishing.
- View API documentation in a test environment
Confirm discoverability and content in test space.
Integration and service management
- Add your service to the service manager
Let other teams run your service in their local setup
Monitoring and alerting
- Add a logs dashboard
See the requests and errors that matter for your service
- Add a metrics dashboard
Track request rates, response times and error rates
- Set up alerting for your team
Create accounts for everyone who will be on call
- Add alerts for your service
Choose what triggers an alert and who it reaches
Readiness and compliance
- Create a platform readiness assessment
Meet 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.
Getting started
Design an API
Overview of the steps to design, specify, and document an API microservice.
Prepare to build an API
Get the standards and approvals lined up before you write any code.
Research and document an Alpha API
Steps for teams documenting an API during its Alpha phase.
Research and document an API
Plan and document the API journey from early discovery.
Repository
Create a repository for your API
Scaffold a repository from the platform template.
Specification
Write the OpenAPI specification (OAS)
Define your API using OAS 3.0.3 — info section, security schemes, and paths.
Update the API overview
Explain purpose, usage boundaries, and related guidance.
Create an end-to-end service guide or roadmap
Create structured guidance for service delivery.
Access and authorisation
Manage API authorisations and access
Overview of the access control guides to follow before managing API access.
Set up API access scopes
Define and manage OAuth scopes for user-restricted and privileged applications.
Assign access levels to an API endpoint
Add application-restricted or user-restricted security to each endpoint in your OAS.
Configuration
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.
Generate testing credentials
Generate credentials to authenticate requests while testing an API.
Documentation validation
Preview API documentation locally
Validate rendered documentation before release.
View API documentation in a test environment
Confirm visibility and clarity in published test docs.
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.