An API Governance Framework for SkillsFuture Singapore's API Platform
- A four-stage API lifecycle with entry and exit criteria at each stage gate
- Separate governance for teams that build APIs and teams that use them
- Design guidelines requiring OpenAPI and JSON Schema for new APIs
- An access model based on each API’s audience and type
- Customer
- SkillsFuture Singapore (Sakura Sky as subcontractor)
- Year
- Topics
- Api, Governance, Security
If you run an API platform across many teams, you are governing two groups at once: the teams that publish APIs and the developers who use them. SkillsFuture Singapore (SSG), the Singapore government agency for skills development, runs an API platform through which developers connect their applications to SSG systems. Sakura Sky worked on the programme as a specialist subcontractor and wrote its API governance framework. Today this kind of work is part of our Cloud practice.
The brief
The scope called for an API governance framework covering the API lifecycle, design guidelines, policies and terms of use, governance roles, and the metrics used to judge success. Sakura Sky wrote the framework, drawing on public references such as Google’s API Design Guide and Microsoft’s REST API Guidelines. Version 3.4 was issued in May 2020.
What the framework covers
The framework splits the API value chain into two halves: Service Provider Governance for the teams building APIs and Service Subscriber Governance for the developers consuming them. The two groups have different needs and carry different risks.
- Lifecycle stage gates. The framework routes provider APIs through four stages (Inception, Build, Adoption, and Close), and each stage gate has its own entry and exit criteria. Changes to published APIs follow a separate change-management workflow. Subscribers have a lifecycle of their own: Registration, Subscription, Build, and Adoption.
- Design guidelines. Seven groups of provider guidelines, from general principles to security, use RFC 2119 keywords such as MUST and SHOULD. New APIs must be defined with Swagger (OpenAPI) and JSON Schema, subject to approved exemptions. REST conventions and the OWASP REST Security Cheat Sheet are the recommended baseline, and the framework also recommends semantic versioning, with explicit lists of breaking and non-breaking changes.
- Access by risk. Each API is classified by type (query or transactional), audience (open, partner, or exclusive), and data sensitivity. Registered developers can subscribe to open APIs directly, partner and exclusive APIs go through approval, and subscribers to transactional APIs can be required to pass conformance testing before they get production access.
- Service levels. Providers get an SLA template that draws on the European Commission’s 2014 cloud SLA guidelines, and every service level objective must name something measurable, such as performance, scalability, or availability.
- A hybrid operating model. The framework recommends making platform-wide decisions centrally and letting teams choose the rest from preset options in its templates, and it defines the roles involved, from the API team and platform manager to requesters and API owners.
- Measuring progress. Developer adoption is the main success metric, and the framework warns against counting APIs as a measure on their own. It recommends a quarterly maturity assessment with Apigee Compass, and a baseline assessment was run in March 2020.
Version 3.4 runs to 64 pages, with separate appendices that include request templates, a compliance checklist, an SLA template, a metrics checklist, and BPMN workflow diagrams for the provider and subscriber lifecycles. It was written to be revised as the programme matured.
If you’re setting up governance for an API platform shared by many teams, talk to us about where to start.