API Governance Reference  

When an organization looks to scale its API Program, it often introduces the need for stricter governance. This ensures quality and consistency across teams. Here is an example of a Governance Summary that may be used on an API Program.

API Design Standards

• Pragmatic REST API Design
• Consistent API Versioning - /grouping/v2
• JSON payload format as standard
• Consistent Error Format
• Reuse APIs proxies and policies where possible
• Consistent Naming Conventions

Security Standards

• All APIs should be protected with OAuth 2.0
• Communication between API Proxies and backend services should be protected with Mutual TLS
• IP allowlisting should be implemented between Apigee and the Target Systems
• A centralised Identity Provider will be used for all API token issuance

Software Development Lifecycle

• All code should be stored in source control and use GitLab flow branching strategy
• Code can only be deployed using Continuous Integration in all environments except dev
• Complex custom code should be unit tested using JUnit for Java and Mocha for JS.
• All APIs should be integration tested, with apickli as the recommended library.
• Releases should progress through each of the Organization and Environment stages
  • Development
  • Integration
  • Performance Benchmarking
  • User Acceptance Testing
  • Preproduction
  • Sandbox
  • Production

Common Proxy Functions

• Proxies should be created from a central Proxy Template
• Common functions like logging, token validation and error handling should reuse central Shared Flows

API Specification

• All APIs should be documented as OpenAPI Specifications
• Mocks can be derived from OpenAPI Specifications
• Developer Documentation can be derived from OpenAPI Specifications

Maintenance and Support

• SLAs should consider the SLAs of downstream services
• Deprecated API versions will be supported for 6 months from deprecation
• API Status must be communicated through the Developer Portal
• API Support is provided by the Support team using their standard practices

API Monitoring

• All APIs will be monitoring using centralised monitoring tools
• All APIs should implement /ping and /status API endpoints

Logging and Analytics

• All APIs should log to a centralised logging system
• Log format should be consistent and contain the minimum standard fields
• All APIs should provided consistent Analytics

Role-Based Access Control

• Developers should have access to all functionality in the nonprod organization
• Operations should have access to all functionality in the prod organization
• Business users should have access to Analytics in all environments
• Continuous Integration service accounts should have access to only deploy in all environments

Developer Engagement

• All API documentation will be published on a central Developer Portal
• Clients must onboard to use APIs via the central Developer Portal
• API sandboxes must be available for consumption by the Developer Portal
• Internal APIs can be privately published to restrict availability to internal users

Delivery Methodology

• Development teams should prefer iterative over waterfall methodologies.
• APIs should be treated as Products and not only technical assets

Team Structure

• A Virtual API team as described here

Execution

• The Platform team will decide between Policeman, Teacher and Referee for any breaches of the guidelines
• Scrum development methodology will be used, with a Product Owner as a full time member of the API team