Establishing Best Practices for API Architecture and Standards

A strong approach to API development is one that is driven by business value and objectives and governed by reference architecture and standards. It is common for companies to develop sets of APIs for point projects only to find that after years of project-based development, they have hundreds of APIs built with little commonality and a great deal of redundancy.

Great success has come from building API strategy and standards based on SOA concepts and approaches. For example, having some governance around the creation of API standards and checkpoints within the development process to look for strategic value, potential reuse and to ensure standards-based development.

The following is an API Assessment to better align your API strategy with your business goals to determine the proper level of investment in API standards and processes:

Assessment Activity

Conduct interview sessions on the following topics:

• Business Model and Strategy
• Enterprise Architecture and Strategy
• Integration and Service Architecture
• Service Inventory
• Stakeholders
• Business Strategy
• Digital Strategy
• Marketing Strategy
• Consumer Engagement Strategy
• API impact to current capital projects

Assessment Deliverable

API Business Strategy Assessment Findings Report including:

• Competitive Overview
• Business Benefits and Opportunities
• Business Case Considerations

Technical Strategy Activities

The technical API strategy consists of the following activities:

•  Review current state of API standards, architecture and development processes.
•  Identify gaps in API technical strategy and collaborate with the client to define standards and processes to close these gaps

The key deliverables from the Technical Strategy includes:

• Assessment report of Key Findings and Recommendations
• Technical Readiness Scorecard
• Service Strategy Recommendations
• API Standards Activities

Within the context of the client’s current state collaborate with the client to create API architecture principles and guidelines.

Establish Intuitive API design standards including:

• URI design
• Use of HTTP verbs
• Subdomains
• Attribute naming standards
• Define API design patterns

Define API architecture standards for the following:

• Support for XML and/or JSON
• Pagination
• Metadata in the API response
• Request validation, Error handling, error metadata in the response, and HTTP status codes
• Internal service abstracts for external APIs
• Change management and version control
• Search functionality
• Architecture for throttling, security, exceptions, metrics and reporting
• Security standards for authentication and authorization

The key deliverables for API Standards include:

API Architecture Guidebook including:

• Architecture Principles for API Software
• Design Patterns and Conventions
• Definition of common API patterns
• Definition of standard API toolsets
• API Governance and Organizational Considerations
• Key Roles and Responsibilities

API Developers Guidebook including:

• Status codes and Error Handling
• Naming
• Versioning
• Logging and Auditing
• Developer Portal
• API Architecture and Design Practices
• Security
• Runtime Governance
• Testing
• Change Management
• DevOps Considerations

Perficient has a set of best practices, guidebooks and templates to help get your API program on track to deliver business value, agility and technical excellence. Please contact Perficient for details.