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
LinkedIn
Twitter
