apidays LIVE LONDON - The Road to Embedded Finance, Banking and Insurance with APIs
API Standards and Governance Platform
Nicoleta Stoica, Lead API Architect at HSBC
Emergent Methods: Multi-lingual narrative tracking in the news - real-time ex...
apidays LIVE LONDON - API Standards and Governance Platform by Nicoleta Stoica
1. Date:Oct 2020
Prepared by: Nicoleta Stoica
Lead API Architect, HSBC Wealth and Personal Banking
API Standards and Governance Platform
PUBLIC
2. 1 PUBLIC
Why and how does HSBC Wealth and Personal
Bank implement API Governance across the
organization?
3. 2
API Standards and Governance: Who pays the price?
Without API standards & governance the costs to use HSBC APIs are multiplied.
PUBLIC
XL Effort
Small Effort
waterline
Build Effort to use Payments Build Effort to use Transactions Build Effort to use Balances
Standardization Effort
Build Effort to use HSBC API
WithoutStandards&
Governance
WithStandards&
Governance
Challenges:
• Increased cost to useAPIs
• LimitedAPI reuse
• InconsistentAPI Quality
• Interoperability issues
Benefits:
• Lower cost to useAPIs
• Increased API reuse
• Increased API quality
• Improved Reputation
• Improved API experience
waterline
4. 3
Lesson #1: Investing in API standards will benefit both API Consumers and API Providers
PUBLIC
API Design Standards
(Interface Contract)
API Development Standards
(Implementation)API Consumer API Provider
API Design Standards Roadmap API Development Standards Roadmap
Continuousimprovement&CostEffectiveness
Continuouscompatibility&ImprovedAPIExperience
Consistency & stability of the interface contract Engineering consistency
2019
2020
2021
v1
v2
v3
Backwards
compatible
Backwards
compatible
Improve &
Automate
Improve &
Automate
Developer
Developer
Developer
Developer
5. 4
Lesson #2: Focus API Design reviews on API Product vision and automate what you can in order to scale
PUBLIC
API Designer
API Documentation
API Contract
Request
API review
API Reviewers API Repository
Have we build
the right API?
PublishAPI
Contract
Proceed with build
[Approved][ConditionalApproved][Dispensation]
[Resubmit]
[approved]
[not-
approved]
API GovernanceTool
Check compliancy
Have we build
the API right?
6. 5
Lesson #2: Focus API Design reviews on API Product vision and automate what you can in order to scale
PUBLIC
Automate API Style checksAPI as a Product
Does your API use a consistent
style to lower learning curve?
Is your API intuitive?
Focus on the usability, the
support model, the cost.
7. 6
Lesson #3: Promoting domain driven design approach across the enterprise will increase API reuse
PUBLIC
API Governance promotes an outside-in business
domain driven design approach across the enterprise
for guiding identification, development, evolution
and standardisation of API contracts
By focusing on the domain it helps to establish area
of concern and the separation of services
Mapping APIs to a particular domain will increase API
reuse by making the APIs discoverable
APIAPI
Domain C
APIAPI
APIAPI
Domain B
APIAPI
APIAPI
Domain A
APIAPI
8. 7
Lesson #4: Using common vocabularies based on a standardised language will create homogeneous APIs
PUBLIC
API Contract
X-HSBC-Header 1
….
Data object 1
Data attribute 1
Data attribute 2
----
Data Attribute n
Data object 2
Data attribute 1
Data attribute 2
----
Data Attribute n
Request/ResponseHeader
API Governance team defines and
maintains a catalogue of core
schema definitions across the
enterprise
We are taking influence from
successful initiatives such as
schema.org.
API Designer should
pick-up data objects and data
attributes definitions from
common schemas where
those exist.
9. 8
API Standards and Governance Platform
API Standards and Governance Platform - Core Services
PUBLIC
API Standards Definition API Governance Processes andTooling
API Design
Standards Definitions Automated Validation
Governance
Dashboards
Certifications
API Implementation
Standards Definitions
Define high quality, consistent API experiences Validate standards at scale
API Reference
Implementations
API Governance
Metrics definition
API Checklists
definition
Common Vocabularies Definition API Reviews Process API Repository
10. 9
☑ Basic API Design standards
☑ Basic API development standards
☑ Manual governance checklist
☑ API Design reviews
API Standards and Governance Platform - High Level Roadmap
PUBLIC
Brilliant Basics
☑ API Design Standards that improve theAPI experience
☑ AutomatedGovernance Engine
☑ Integrate API Governance Engine with CI/CD deployment
pipelines
☑ API Design Standards that drive a market leadingAPI experience
☑ API development standards that drives cost effective API development
☑ API Reference Implementations
☑ API Standards as Code (e.g https://google.aip.dev/)
☑ API Governance Metrics definition and Dashboards
Automation
Scale
Continuous
Improvement
Continuous
Improvement
11. 10
Recap: API Standards and Governance Platform
PUBLIC
API Standards and Governance Platform - High Level Roadmap
API Standards and Governance Platform - Core Services
Lesson #4: Using common vocabularies based on a standardised language will create homogenous
APIs.
Lesson #3: Promoting domain driven design approach across the enterprise will increase API reuse.
Lesson #2: Focus API Design reviews on API Product vision and automate what you can in order to
scale.
Lesson #1: Investing in API standards will bring benefits to both API Consumers and API Providers.
Hi everyone and thank you for joining me today for the API Standards and Governance Platform Session.
I am the Lead API Architect for HSBC Wealth and Personal Banking and I will be sharing today why and how does HSBC Wealth and Personal Bank implement API Governance across the organisation.
Lets look first at who pays the price for lack of API standards and Governance within an organisation.
At HSBC, we embarked on a digital transformation several years ago and we have built since hundreds of APIs every year.
Without API Standards and Governance platform, we were experiencing limited API reuse, increased cost to use existing APIs, inconsistent API quality and interoperability challenges across different service lines.
We soon realized that we need to invest in standardisation in order to lower the cost on the consumers to use APIs, increase API reuse and overall API Quality by delivering market leading API experiences to both internal and external API consumers.
If your organisation is one that has many APIs with duplicate functionality, APIs that are called by only a single API consumer, I will be sharing few lessons learned as part of our jounery that can help addressing these challenges.
Lesson 1: Invest in API standards definition as this will benefit both API consumers and API providers.
At HSBC we have defined both API Design standards and API Implementation standards.
API Design standards benefit API consumers as they provide a set of consistent interface structures & behaviours & patterns expected across all APIs such as error structure, error codes, request/response format, pagination, sorting, versioning.
API implementation standards allow API Providers to improve implementation approaches for cost-effective API development and maintainability including consistent availability, security and performance characteristics such as common logging, monitoring and security patterns across all our APIs.
The two standards are complementing each other and can evolve at different rates.
API Design Standards aim to always be backwards compatible for the benefit of the consumer. API standards evolve and improve over time but new releases are always backwards compatible using a never remove, only add approach.
API Implementation Standards can rapidly evolve to use better approaches for the benefit of providing a cost-effective API.
API Design and Development standards are governed by a central API Platform team within HSBC.
Lesson 2: Focus your API Design Reviews on API Product vision and automate what you can in order to scale.
API Design Governance at HSBC is the result of collaborative work between API Architects, API Designers, API Product Owner and API Consumers.
API Designer is responsible for the design of the API product in alignment to the approved HSBC’s API standards. API Designer prepares the API Product documentation and the API contract including the API meta-data for discoverability purposes.
API Designer will make use of the API Governance Tool to check compliancy with the API standards as he is designing his API and before submitting his API for review to the API Review Board.
The API Review Board is chaired by a senior API Architect who brings together API reviewers that will review the new API Products or significant changes to existing API Products.
API Architect is responsible for reviewing the API Product documentation and provide expert advice on key API design decisions in alignment with the API governance strategic objectives (e.g reusability and consistency, security) and API Product vision ensuring that we build a product that can evolve over time and we do not build just for the use cases in front of us.
API Business Architect is responsible to ensure API functional scope is aligned to the business domain model and provide expert advice on business language and terminology to be used.
API Product Owner is responsible for the definition and communication of API Product Feature Roadmap and Vision to drive
the design of the API Product.
At HSBC we don’t understand API governance as a way to impose a certain way of doing things, but as a consulting service provided by API Design/ Architects experts that help internal stakeholders optimize their APIs by asking simple questions and demonstrating areas for improvement.
The most important thing is to avoid changes that are not backwards compatible and that may impact the whole consumer chain.
API governance members are putting themselves always into their consumers’ shoes.
By automating validation of our API Designs we are able to remove process bottlenecks, shift validation earlier in the development cycle and reduce overall governance costs.
Automating API Governance is key to scaling our governance process across Wealth and Personal Banking globally.
API Governance team treats APIs as products.
Do you have a Product Roadmap for your API? What features does your Product need to support? Do we have a good understanding of the use cases that your API Product will enable now or in the future?
API Governance teams thinks about the API Developer Experience.
How can you make it easy for developers to use your API? Is it intuitive, does it use a consistent style to lower learning curve?
What is to the support model for your API? How would you allow changes to your APIs to support other teams/ service lines?
What is the cost model for your API?
What is the registration Process for your API? How will other register to consume your API?
How easy is for your API to be found in the API repository? Have you tagged it with relevant meta—data?
API Governance team provides tooling that help automate API Style checks. This allows problems to be flagged early and fixed early in the design process before the actual implementations are developed.
How do API Consumers benefit from API providers having an API Governance?
All APIs are designed in the same way(error structure, error codes, request/response format, pagination, query parameters, versioning).
They have the same documentation format, the same type of materials (RAML/ OAS) and are ready for developers to start coding.
All APIs have Clear, Consistent, Comprehensive and Correct documentation.
Our APIs are interoperable and can be combined to create valuable customer experience.
Our APIs use a Common Data Dictionary.
ALL API contracts are published to a centralised API repository with relevant meta-data so that APIs can be discovered and reused.
API Governance promotes a business domain driven design approach across the enterprise for guiding the identification, development, evolution and standardisation of API definitions.
By focusing on the domain it helps to establish area of concern and the separation of services.
Mapping APIs to a particular domain will increase API reuse by making the APIs discoverable by allowing someone to drill down through a business domain model and find the APIs.
API Governance team defines common vocabularies based on a standardized language already in use and publish those as reusable schemas across the enterprise.
We recognise the importance to maintain a catalogue of core schema definitions across the enterprise.
We are taking influence from successful initiatives such as schema.org.
API Standards and Governance team at HSBC Wealth and Personal Bank is providing a set of Core platform services:
API Standards definition that help define quality and consistent API experiences
API Governance process and tooling that help validate standards at scale and ensure we build the right APIs for HSBC.
Our API Governance is simple and effective and is continuously improving based on feedback from our internal stakeholders.
Looking back at our journey so far, we started with few brilliant basics.
Start by defining basic API design and development standards and checklist to enable teams to perform self-assessments.
Automation will help remove process bottlenecks, shift validation earlier in the development cycle and reduce overall governance costs.
Checklists are implemented as rules in our API Governance tool that API designers and API Architects can use to quickly check compliancy to the design standards ( those that can be automated).
Our CI/CD deployment pipelines are integrated with the API Governance tool and non-compliancy to standards is made visible to the Chief API Architects and Internal Auditors via our API Governance Dashboards.
Further automation – manage your API standards as code! We re inspired by initiative such as https://google.aip.dev/ (API Improvement Proposals).
API Reference Implementations are a developer accelerator as allows developer to be focusing on the business logic specific to the API while common capabilities such as logging, monitoring, security, caching are implemented in a consistent with the help of common libraries.
Standards evolve over time. By managing API standards as code it would be very easy to version and label them. For people to see a clear history of changes. Also to build further automation – like a chatbot that parses the standards and best practise. Finding out what has changed across all standards would be easy, and possibly the impact on projects.
By measuring key API Governance metrics such as no of consumers for an API, volume of traffic for an API, APIs published to the API repository, no of days from when an API is submitted for review to approval, we are able to drive the correct behaviour across our organisation and continuously improve our processes.