Validating API Design Requirements for Interoperability: A Static Analysis Approach Using OpenAPI

TL;DR

This paper introduces S.E.O.R.A, a configurable static analysis tool that automates validation of API design rules in OpenAPI specifications to improve interoperability, governance, and early quality assurance.

Contribution

It develops a configurable rule engine for API design validation based on 75 rules, supporting customization and integration into development workflows.

Findings

Automates early validation of API non-functional requirements.

Provides actionable, traceable feedback for API design improvements.

Enhances API quality assurance through automated rule checking.

Abstract

RESTful APIs are central in developing interoperable, modular, and maintainable software systems in enterprises today. Also, it is essential to support system evolution, service interoperability, and governance across organizational boundaries to ensure good quality and consistency of these APIs. However, evaluating API design quality, which is part of non-functional requirement tasks, remains a largely manual and ad hoc process, particularly during early development. Using a Design Science Research (DSR) methodology, we elicited user needs, identified 75 API design rules using a literature review, and implemented a configurable rule engine to detect structural violations in OpenAPI specifications. The proposed tool supports organizational adaptability by allowing rules to be customized, enabled, or disabled, enabling integration of domain-specific standards. The evaluation was conducted through structured experiments and thematic analysis involving industry experts. API quality validation contributes to aligning technical designs with requirements and enterprise architecture by strengthening interoperability and governance between enterprise systems. The results show that S.E.O.R.A facilitates early validation of non-functional API requirements, provides actionable and traceable feedback, and aligns well with requirements elicitation and quality assurance processes. It improves the API design process by automating checks that would otherwise require manual inspection, thus supporting consistent and reusable conformance practices. This work contributes to requirements engineering by operationalizing design principles as verifiable constraints and embedding them into a practical validation tool. Future directions include IDE integration, expanded rule coverage, and real-world deployment to support continuous compliance in agile API development lifecycles.