Skip to content

Commit 9ea2519

Browse files
spikeheapspikeheap
committed
Migrate & fix API Playbook
This commit migrates content from LBHackney-IT/API-Playbook@2e9f801 = Also Fix API-Playbook links, frontmatter & TextToSpeech component We no longer need the text to speech component as there are screen reader technologies we are/should be compatible with
1 parent 2574aa7 commit 9ea2519

File tree

155 files changed

+6181
-9
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

155 files changed

+6181
-9
lines changed

‎docs/api-playbook/02-Release Notes/release-notes-v3.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
id: release-notes-v3
3+
title: V3
4+
---
5+
*Product Name: API Playbook*
6+
*Version: V3*
7+
*Release Date: January 2021*
8+
9+
## Version 3:
10+
11+
## Target Audience:
12+
13+
All HackIT internal developers and external agencies developer collaborating on Hackney projects.
14+
15+
## Enhancements:
16+
17+
- Align the API playbook with the new design system to maintain consistency across the board;
18+
- Self training modules;
19+
- Serverless Lambda framework;
20+
- Linting;
21+
- Static Code Analysis;
22+
- DevOps Practices (including videos);
23+
- Updated API boilerplate;
24+
- Monitoring and alerts via Cloudwatch canaries;
25+
- Uptime Monitoring using X-Ray;
26+
- Performance monitoring using Lambda Insight;
27+
- Standardised Error Messages;
28+
- Preferred Tech Stack;
29+
- API Boilerplate - Base API;
30+
- Clean Architecture;
31+
- Entity Framework;
32+
- AWS/ECS with Fargate;
33+
- Lambda Functions;
34+
- Docker Containers;
35+
- Application Logging Guidelines;
36+
- Lambda Authoriser;
37+
- Setting Up DMS;
38+
- Pipeline Implementation;
39+
- End to End Training - Create your First endpoint video;
40+
- Contact Us;
41+
42+
## Feedback:
43+
44+
We would be pleased to hear from you about our new iteration of the API Playbook. Please feel free to give us your feedback.

‎docs/api-playbook/02-Release Notes/release-notes-v4.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
id: release-notes-v4
3+
title: V4
4+
---
5+
*Product Name: API Playbook*
6+
*Version: V4*
7+
*Release Date: September 2022*
8+
9+
### Target Audience
10+
11+
All HackIT internal developers and external agencies collaborating on Hackney projects.
12+
13+
### Enhancements
14+
15+
*Improvements & New features*
16+
17+
- Re-organising the sidebar sections
18+
- Created new diagrams such as The API Architecture, in order to highlight our High-Level Development Lifecycle
19+
- Allow large image preview on click to ensure that our diagrams and code snippets are visible and easy to read
20+
- Create new content and update the existing one in order to be up to date with the latest technologies and our ways of working
21+
- Record video tutorials for specific sections and technologies in order to enforce learning
22+
23+
24+
**Fixed Issues**
25+
- By organising the sidebar sections, we managed to provide a better structure for our API Playbook; therefore it is easier to understand and search for a specific topic, hence:
26+
- Less time consuming
27+
- More visual
28+
- More inclusive, for people with a variety of disabilities, including visual impairments as users can also listen to the tutorials if preferred
29+
30+
**The following new Contents have been added**
31+
- Terraform Compliance
32+
- Developer Hub Intro Page
33+
- API Specification
34+
- Serverless Safeguards
35+
- Tech Ways of Working: Deploying to production
36+
- NuGet Packages
37+
- Production Testing Checklist
38+
- SonarCloud
39+
- Target Type & Target ID
40+
- Automation of Canaries
41+
- GitGuardian
42+
- FAQ Section
43+
- Support
44+
- Data Migration
45+
- Using SSM to retrieve secrets at runtime
46+
- Development Lifecycle diagram
47+
- Architecture Decision Records
48+
- Developer Onboarding
49+
- API Compliance checklist
50+
- Example PRs for endpoints and tools setup
51+
52+
53+
*New Diagrams added*
54+
- API Lifecycle diagram
55+
- API Architecture Diagram
56+
- Architecture Standards
57+
58+
*New Video Tutorials added*
59+
- Serverless Safeguards
60+
- NuGet Packages
61+
- SonarCloud
62+
- Build API endpoint using OpenSearch (Also known as ElasticSearch)
63+
64+
### Feedback
65+
We would be pleased to hear from you about our new iteration of the API Playbook. Please feel free to give us your feedback.

‎docs/api-playbook/04-Governance/API Documentation/adr.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
id: adr
3+
title: Architecture Decision Records
4+
---
5+
### Context
6+
7+
Previously technical decisions were captured as part of spike documentation that was kept in project specific google drive. They were not open for other projects to review, adopt and adapt. Often, new developers were not aware of decisions as they were not aware of where to look for documentation.
8+
9+
Hence, we agreed to create Architecture Decision Records (ADRs) and add them to a single github repo [https://github.com/LBHackney-IT/lbh-adrs] to ensure that we have enough documentation, that all decisions are kept in the same location that is easy to find and to document how and why a decision was reached within a codebase.
10+
11+
This will also achieve governance and uniformity around all projects. Also ADRs help to give context around the decisions that were taken so that we can revisit them. Other benefits that we have identified when using ADRs are:
12+
- Improves onboarding for new developers
13+
- Improves agility when handing over project ownership between external team to internal or vice versa
14+
- Improves alignment across the teams regarding best practices
15+
16+
### What is an Architectural Decision Record?
17+
18+
An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences of adopting the decision.
19+
20+
### When to write an ADR?
21+
An ADR should be written whenever a decision of significant impact is made; it is up to each project team to align on what defines a significant impact. They can be:
22+
23+
- Backfilling a decision which was made previously.
24+
- Proposing large changes to a solution/spike.
25+
- Proposing no/small changes for a spike
26+
- Proposing changes that differ from the overall agreed standard across our current ecosystem.
27+
28+
### How to start using ADRs
29+
30+
*Decision identification:*
31+
- How urgent and how important is Architecture Decision?
32+
- Design methods and practices can assist with decision identification and decision making.
33+
- Ideally maintain a decision to-do list which aligns with the service to-do list.
34+
35+
*Decision making:*
36+
-Group decision making via Community of practices or project team workshops to validate the findings can help in decision making.
37+
- Better informed decision via ADRs which are available openly and people can collaborate on it.
38+
39+
*Decision enactment and enforcement:*
40+
- ADRs are used in software design; hence they have to be communicated to, and accepted by, various stakeholders of the services that fund, develop, consume and operate it.
41+
- Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices.
42+
- ADRs also have to be (re-)considered when modernizing a software system in software evolution.
43+
44+
*Decision sharing (optional):*
45+
- Many ADRs recurring across various project development..
46+
- Experiences from other projects and reusable components could enforce knowledge management strategy and contribute towards our emerging Community of practices meetups such as Data and Architecture etc.
47+
- Dependency matrix evaluation.
48+
49+

‎docs/api-playbook/04-Governance/API Documentation/api_specification.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
id: api_specification
3+
title: API Specification
4+
---
5+
6+
An API specification provides a broad understanding of how an API behaves and how an API links with others. At HackIT, we explain how the API functions work and the results expected when using our APIs.
7+
We can also understand more in depth the relationships between the objects and how each object can be used.
8+
9+
10+
The goal of our API specifications is to standardise data exchange between web services in “The HackIT way”. In this case, standardisation means the ability of diverse systems, written in different programming languages and by using different technologies, to seamlessly communicate with each other.
11+
12+
For more information about our API Specification, please visit the below link:
13+
[API Specification](https://lbhackney-it.github.io/api-specifications/)

‎docs/api-playbook/04-Governance/API Documentation/swagger_documentation.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
id: swagger_documentation
3+
title: Swagger Documentation
4+
---
5+
6+
## Introduction:
7+
8+
At Hackney, we believe in working in a collaborative way and this is embedded into our API development process. Before commencing the implementation stage, each API endpoint will first need to be documented using SwaggerHub.
9+
10+
The benefits of this include:
11+
- Open specification standards;
12+
- Opportunity to mock the API and avoid possible blockers for front end development;
13+
- Opportunity to share and reach a common agreement of what the API request and response should look like before any work has commenced;
14+
## Purpose:
15+
16+
The documentation aids our collaboration process, as it is shared with the whole team. People, both from technical and non-technical backgrounds, can provide feedback and request changes. This can save hours of development and also ensures that every team member has an understanding of the main question — what will this API do?
17+
18+
We have chosen SwaggerHub as a tool to document our APIs as it contributes to the efficiency of our development process, by giving us a central point of reference, built collaboratively, with a defined objective for the eventual shape of the API.
19+
20+
## What is SwaggerHub?:
21+
22+
** You can start by watching our overview video: **
23+
24+
<figure class="video-container">
25+
<iframe width="100%" src="https://www.youtube.com/embed/QYQNgeDuqok" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
26+
</figure>
27+
28+
** SwaggerHub ** is an integrated API development platform that brings together all the core capabilities of the open source Swagger framework, along with additional advanced capabilities to build, document, manage, and deploy your APIs.
29+
30+
SwaggerHub allows us to build an implementation specification, and serves as documentation for the API we are developing. In this way, developers have clearly defined requirements of how the API endpoint they are working on needs to look — this includes request parameters, response object and error responses.
31+
32+
Additionally, we share the API blueprint with other relevant parties, such as the Product Owner, to confirm that the data, that is part of the request and response of the API, is correct, based on the business area understanding of the wider team and any prior discovery work completed. It is a way of getting everyone from the team to work towards the same, shared goal.
33+
34+
## Documenting APIs:
35+
36+
The process of documenting API endpoints involves working with a YAML file, where we would specify information such as the path to the API endpoint, the search parameters, API response object, the data types used and whether input fields are mandatory or not.
37+
38+
39+
![YAML file](../../doc-images/swagger_yaml.png)
40+
41+
_The YAML file_
42+
43+
![Open API generated documentation](../../doc-images/swagger_generated_spec.png)
44+
45+
_The generated documentation_
46+
47+
SwaggerHub’s online editor automatically validates the YAML file produced and allows developers to instantly see any changes they make by reflecting them onto the visual representation of the API endpoint. For easy visualisation, SwaggerHub interprets the OpenAPI document as easy to read documentation. This UI clearly lays out the endpoints for the API, which the development team can use for reference when writing code.
48+
49+
![Example payload](../../doc-images/swagger_example_payload.png)
50+
51+
![Models used in the response](../../doc-images/swagger_models.png)
52+
53+
_The documentation outlines an example payload and the models which will be used_
54+
55+
Documenting the API with SwaggerHub means that we have a consistent specification to follow throughout the development of the API. This is beneficial for the team as we can refer to the swagger docs to confirm that the API is functioning as specified and that the completed API matches the swagger doc specification.
56+
57+
At the end of the project, we can continue to use SwaggerHub as documentation, giving an easy summary of the functions of the API.
58+
59+
Additionally, SwaggerHub provides a way to mock the APIs developed via the tool and make requests against them. This is particularly useful when front end and back end teams are working on the same project. Often, front end work might get blocked as it has a dependency on an API.
60+
Providing a mock API and API blueprints will remove this blocker as it will give the front end developers all the information they need to proceed with their work, while back end developers can focus on developing good, reliable and resilient APIs.
61+
62+
**This is highly important as it avoids the situation where back-end developers would be rushed to deliver thier work in a quicker manner so that it doesn't block other project work, which may result in lower quality APIs. **
63+
64+
## SwaggerHub Standards:
65+
66+
We utilise two of SwaggerHub's functions to document the status of our APIs: **tagging API environments** and **publishing API specifications**. These allow us to track whether an API is active and what environments it is available in. These also automatically sync with our [Developer Hub](https://developer-api.hackney.gov.uk/). To see more about the Developer Hub, please refer to the [relevant page](/developer_hub).
67+
68+
### Tagging API Environments:
69+
70+
As part of of the process of documenting APIs at HackIT, you should use tags to track the environments an API is deployed in.
71+
72+
The four available tags are: **Development / Staging / Production / Deprecated**.
73+
74+
The screenshow below provides an example of how the relevant tags can be added to an API specification:
75+
76+
![Example payload](../../doc-images/swaggerhub_tags.png)
77+
78+
Utilise the **Deprecated** tag to show when an API or specific version is deprecated. These tags are version-specific, so you can choose to deprecate a specific API version when it is no longer supported, or add `Deprecated` to each version to signify that the entire API is deprecated.
79+
80+
### Publishing APIs:
81+
82+
Once the API specification has been created and approved and the API is in a stable state, the next step is to publish the specification on SwaggerHub. This signifies that this API is ready to be used and the API will be marked as 'Active' on the Developer Hub.
83+
84+
*Note: Doing publishing an API version locks it to read-only mode. Take this into consideration and only publish an API version once it is finalised.*
85+
86+
## Where to find SwaggerHub:
87+
88+
Hackney SwaggerHub is located at https://app.swaggerhub.com/organizations/Hackney.
89+
90+
All the Platform APIs in development have been documented and are viewable on the SwaggerHub.

‎docs/api-playbook/04-Governance/api_compliance.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
id: api_compliance
3+
title: API Compliance
4+
---
5+
6+
### Context
7+
Every API deployed to development, staging and production environments must be compliant with the set of standards listed in this document. An API should not be promoted from one environment to another if it does not satisfy all requirements listed.
8+
9+
The set of compliance items that form this checklist are put in place to ensure that any API developed does not duplicate effort, is built in a reusable way, follows security best practices, is consistent with other APIs and follows all development standards defined.
10+
11+
The APIs compliance checklist will be used as part of future Service Standard Assessments and ongoing check-ins to ensure any identified issues are tackled early on and no technical debt is accumulated.
12+
13+
### Checklist
14+
1. The API has corresponding SwaggerHub documentation for all of the API endpoints it exposes.
15+
2. The API has completed the [API specification assessment process](https://playbook.hackney.gov.uk/api-specifications/assessment_process/)
16+
3. The API has been developed in Hackney’s preferred tech tech stack, unless otherwise agreed and as per standards defined in our [API playbook](https://playbook.hackney.gov.uk/API-Playbook/).
17+
4. The API has been developed following the TDD approach and has end-to-end tets in place
18+
- End-to-end tests guide for DynamoDB
19+
- End-to-end tests guide for PostgreSQL
20+
5. The API has monitoring and logging tools enabled, as per defined standards.
21+
- X-Ray is enabled for request tracing
22+
- Canaries are created for availability monitoring
23+
- CloudWatch is used for application logging.
24+
6. The API has vulnerability scanning enabled via SonarCloud.
25+
- The API should also have no pending findings to review in SonarCloud.
26+
7. The API has the following infrastructure compliance checks in place:
27+
- Terraform-compliance for the AWS resources provisioned as part of the same API deployment
28+
- Serverless safeguards to ensure that the API is using an authorizer for security
29+
8. In Production, the API has been tested as per the ‘Production testing checklist’
30+
9. In Production, the API’s infrastructure is built as per [Production deployment - Live service infrastructure requirements](https://docs.google.com/document/d/1UrT6u4j8AlyPf-aD_E4c30uH27MJgIJoVxYR9kKGzFw/edit)
31+

‎docs/api-playbook/04-Governance/developer_hub.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
id: developer_hub
3+
title: Developer API Hub
4+
sidebar_position: 3
5+
---
6+
### Developer Hub
7+
8+
As an Organisation we want to ensure that our APIs are modern, easy to access and easy to use. We also want to provide clear documentation, accessible test environments, a simple onboarding process and good quality help and support to our users.
9+
Hackney Council’s aim as an organisation is to make integration easier - for everyone who wants to connect to our platforms and services. Whether you’re already using our APIs, or want to connect for the very first time, The Developer Hub is a way to make that journey easier and faster for all our users.
10+
To achieve this mission, we are:
11+
- Building an API platform - a one-stop shop for all our APIs, old and new
12+
- Building an exemplar API
13+
- Migrating our other APIs to the platform
14+
15+
16+
Here is a link to our Developer API Hub:
17+
18+
[Developer API Hub](https://developer-api.hackney.gov.uk/)

0 commit comments

Comments
 (0)