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

TL;DR

The paper tackles the challenge of ensuring API design quality early in REST/OpenAPI-based development by translating established REST design principles into machine-verifiable rules and implementing a static-analysis tool, S.E.O.R.A. Using Design Science Research, it demonstrates how a rule-engine and OpenAPI parser can detect structural violations and provide actionable feedback without deploying services. The authors conduct a structured design process including rule discovery (75 rules), requirements elicitation (from developers), and iterative artifact development and evaluation with industry experts, showing benefits for early validation and governance. Limitations include the OpenAPI expressiveness bounds and potential false positives, but the work highlights practical integration possibilities with requirements engineering and future directions such as IDE/CI integration and broader rule coverage. Overall, S.E.O.R.A offers a configurable, reusable approach to enforce design conformance and support enterprise interoperability in agile API lifecycles.

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.

Figures (2)

• Figure 1: Rule violation interface showing expanded drop-down menu for disabling individual or all rules for a specific key.
• Figure 2: Tree structure visualization of two URIs with highlighted variable {instance_id} used across multiple API methods.