API Governance pt.1: API Validation Framework

Validation of APIs focuses on APIs being complete, consistent, secure and compliant.

Complete:

1. Are mandatory schema sections of the OAS completed (this may include organization-defined mandatory custom fields)?
2. Can the API be considered complete in terms of capabilities/functionalities it is supposed to embody in the current release?

Consistent:

1. Does the API and its corresponding code honor agreed-upon standards for naming and version control?
2. Is there consistency in how the code is written or how cross-cutting concerns (e.g., logging, schema validation, auditing, token validation, error handling, etc.) are being handled?

Secure:

1. Does the API schema specify a Security scheme?
2. Can access to the API endpoints be authenticated and authorized?
3. When using a JWT for claims sharing, is the API validating that the correct signing algorithm for the token has been indicated?

Compliant:

1. Does the API meet regulatory obligations (HIPAA, GDPR, etc.)?
2. Have enterprise common data models been used where applicable?
3. Is data privacy and secrecy protected in the API?
4. Have compliance deficiencies been documented and approved with clear path and timeline to remediation?

API Validation can be performed at two different points in time: design/development-time and run-time. As the name suggests, design/development-time API validation means during design and development stages the API must follow certain styles and standards, some of which are universally recognized (e.g., OAS, REST, etc.) while others may be custom to the organization (e.g., x- prefixed custom properties in OAS). Run-time API Validation targets the executable version of the API. Many SAST and DAST can generate simulated traffic to test whether the code behavior behind the API matches the contract. For developers the earlier in the design stage they can correct errors and remove critical warnings from code, the better their experience and the less costly it gets for the entire project. So how can organizations inform developers before API validation tests what coding standards need to be complied with?

The traditional approach to this involves maintaining static developer and style guides, combined with manual code reviews. The challenges for most organizations with this approach are documentation maintenance and scaling out with increased number of developers. Updating documents over time remains mostly an after-thought. Collaboration, sharing, and effective iteration management all become manual labor-intensive. Additional complexity arises from the fact that software developers often apply their unique approaches to design and code patterns. Besides, not all software developers are equally skilled. Trying to constantly standardize coding practices at the individual coder level to adapt to the enterprise’s static documentation is near-impossible and a wasted effort.

In this article, I present a practical approach to API Validation:

• Identify all the standards developers must follow – this includes custom standards that apply only within the company (e.g., each API document must include the Business Unit and Cost Center for reporting and financial use cases).
• Maintain a digital repository of the standards and crowd source updates with Wiki-like curation.?Google's ‘API Enhancement Proposals’ (AIP) presents a viable example for this approach. Block of numbers are assigned for guidelines that are global, Google product-specific, and client enterprise-specific. Docs are maintained on GitHub using common GitHub functions such as issues, pull requests, etc. Currency is reflected in real-time and is propagated to everyone simultaneously. For extra maturity, consider storing standards in a ‘Policy as Code’ compatible manner to leverage them programmatically.
• In collaboration with Security-focused groups within your company, select software that have built-in security validations for the above selected standards and can be embedded within IDEs and CI/CD pipelines. Many software come shipped with intelligent features that can spot a coder’s drift from HTTP, OWASP, and JSON standards as they are typing. Linter and style enforcers such as Spectral (an open-source tool by?Stoplight.io) can be scripted to include custom validations.
• Include automated validations and error/warning notifications on developers’ machines and within CI/CD pipelines.- Set the minimum scores or pass/fail criteria for design, development and run-time security tests and allow code promotions only if minimum settings are met or exceeded. Often speed-to-market is favored over score compliance rigidity which may require setting a lower score for a pass than the default shipped with the security products.
• Run-time behavior of APIs should also be governed. As part of a pre-deployment test chain, an independent internal security group can perform penetration tests or apply DAST-centric inspections to verify that the API indeed returns the correct responses and error messages based on its schema. To further support developers in ensuring the consistency of their API designs, one effective approach is to provide them with API specification templates grounded in API archetypes.

Contact me or EPAM for more on API Governance. #api #apigovernance #epam