Prepare to build a Developer Hub API
Before building a Developer Hub API, you need to complete planning tasks and coordinate with platform teams. This ensures your API can be deployed, published, and integrated correctly from day one.
About this page. Adapted from documentation I wrote for a government platform. 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.
Plan your API before you write any code. Getting the standards and approvals lined up first avoids rework later.
Before you start
You need:
- access to the platform catalogue
- a team space in your documentation tool
- agreement from your product owner on what the API is for
Understand the platform standards
Read the platform standards and note how each one applies to your API:
- naming conventions — decide your API's name and check it is not already taken
- versioning — decide how you will version, and what a breaking change means for your consumers
- security requirements — decide which access level each endpoint needs
- public or internal — decide whether third parties outside the organisation will consume it
- documentation — check what you must publish alongside the API
Create your approval page
The publishing team assesses every new API against a shared template, so create your approval page before you contact anyone. It is where each team records its decision.
- Open the API approval process template in the platform catalogue.
- Copy it into your team's space.
- Name the parent page API approval process.
- Start working through the phases in the template.
Contact the teams you need
Which teams you involve depends on what your API does. The API platform team is always involved; the rest depend on your data, your dependencies and whether you are publishing externally.
| Team | When to involve them |
|---|---|
| API platform | Always. They own the approval process |
| Platform security | When your API handles personal or sensitive data |
| Integration | When your API depends on other internal APIs |
| Publishing | When your API will be published externally |
Complete your design
Before you start building, confirm and record:
- the endpoints, and the request and response for each
- how the API authenticates and authorises requests
- what it depends on, and what happens when a dependency is unavailable
- how it returns errors, and what each error means to a consumer
Check it worked
Your approval page exists in your team's space, the teams above have recorded their decisions on it, and your design is documented. You can now create a repository for your API. If you get stuck at any point, your platform support channel is the fastest route to an answer.
Prepare to build a Developer Hub API
Before building a Developer Hub API, you need to complete planning tasks and coordinate with platform teams. This ensures your API can be deployed, published, and integrated correctly from day one.
About this page. Adapted from documentation I wrote for a government platform. 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.
Plan your API before you write any code. Getting the standards and approvals lined up first avoids rework later.
Before you start
You need:
- access to the platform catalogue
- a team space in your documentation tool
- agreement from your product owner on what the API is for
Understand the platform standards
Read the platform standards and note how each one applies to your API:
- naming conventions — decide your API's name and check it is not already taken
- versioning — decide how you will version, and what a breaking change means for your consumers
- security requirements — decide which access level each endpoint needs
- public or internal — decide whether third parties outside the organisation will consume it
- documentation — check what you must publish alongside the API
Create your approval page
The publishing team assesses every new API against a shared template, so create your approval page before you contact anyone. It is where each team records its decision.
- Open the API approval process template in the platform catalogue.
- Copy it into your team's space.
- Name the parent page API approval process.
- Start working through the phases in the template.
Contact the teams you need
Which teams you involve depends on what your API does. The API platform team is always involved; the rest depend on your data, your dependencies and whether you are publishing externally.
| Team | When to involve them |
|---|---|
| API platform | Always. They own the approval process |
| Platform security | When your API handles personal or sensitive data |
| Integration | When your API depends on other internal APIs |
| Publishing | When your API will be published externally |
Complete your design
Before you start building, confirm and record:
- the endpoints, and the request and response for each
- how the API authenticates and authorises requests
- what it depends on, and what happens when a dependency is unavailable
- how it returns errors, and what each error means to a consumer
Check it worked
Your approval page exists in your team's space, the teams above have recorded their decisions on it, and your design is documented. You can now create a repository for your API. If you get stuck at any point, your platform support channel is the fastest route to an answer.
Prepare to build a Developer Hub API
Before building a Developer Hub API, you need to complete planning tasks and coordinate with platform teams. This ensures your API can be deployed, published, and integrated correctly from day one.
About this page. Adapted from documentation I wrote for a government platform. 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.
Plan your API before you write any code. Getting the standards and approvals lined up first avoids rework later.
Before you start
You need:
- access to the platform catalogue
- a team space in your documentation tool
- agreement from your product owner on what the API is for
Understand the platform standards
Read the platform standards and note how each one applies to your API:
- naming conventions — decide your API's name and check it is not already taken
- versioning — decide how you will version, and what a breaking change means for your consumers
- security requirements — decide which access level each endpoint needs
- public or internal — decide whether third parties outside the organisation will consume it
- documentation — check what you must publish alongside the API
Create your approval page
The publishing team assesses every new API against a shared template, so create your approval page before you contact anyone. It is where each team records its decision.
- Open the API approval process template in the platform catalogue.
- Copy it into your team's space.
- Name the parent page API approval process.
- Start working through the phases in the template.
Contact the teams you need
Which teams you involve depends on what your API does. The API platform team is always involved; the rest depend on your data, your dependencies and whether you are publishing externally.
| Team | When to involve them |
|---|---|
| API platform | Always. They own the approval process |
| Platform security | When your API handles personal or sensitive data |
| Integration | When your API depends on other internal APIs |
| Publishing | When your API will be published externally |
Complete your design
Before you start building, confirm and record:
- the endpoints, and the request and response for each
- how the API authenticates and authorises requests
- what it depends on, and what happens when a dependency is unavailable
- how it returns errors, and what each error means to a consumer
Check it worked
Your approval page exists in your team's space, the teams above have recorded their decisions on it, and your design is documented. You can now create a repository for your API. If you get stuck at any point, your platform support channel is the fastest route to an answer.