Текстовий стандарт опису API як інструмент підвищення якості тестування програмного забезпечення

UKR: У сучасній розробці програмного забезпечення якість тестування API-інтерфейсів суттєво залежить від повноти їх документування. Актуальність дослідження зумовлена відсутністю єдиного стандарту для текстового опису API у корпоративній документації - Confluence, Google Docs та аналогічних системах. Встановлено, що бізнес-аналітики наприклад, описують ендпоінти довільно, так в одних документах зазначається лише URL, в інших - лише назва операції, тоді як інформація про параметри, коди помилок та авторизацію відсутня. Це призводить до неповного тестового покриття та збільшення кількості дефектів, що виявляються на пізніх стадіях розробки. Метою дослідження є розробка мінімального стандарту текстового опису API - MADS (Minimal API Description Standard) - та обґрунтування його структури на основі аналізу академічних джерел і реальної практики тестування. Запропонований стандарт містить десять полів, згрупованих у чотири блоки: ідентифікація ендпоінту, вхідні дані, вихідні дані та контекст безпеки. В статті проведено дослідження яке демонструє, що застосування MADS дозволяє тестувальнику безпосередньо формувати повний набір тест-кейсів, що охоплюють позитивні сценарії, граничні значення та обробку помилок, без додаткових уточнень вимог. Як результат це впливає на якість вихідного продукта.

ENG: The rapid adoption of microservice architecture has made application programming interfaces (APIs) the primary integration mechanism in modern software systems. Accordingly, the quality of API testing depends directly on the completeness and structure of API specifications available to testing engineers. In practice, however, the majority of projects document their APIs as informal plain text in corporate knowledge management systems - Confluence, Google Docs, Notion - without adhering to any unified standard. A systematic analysis of four current ISTQB syllabuses (CTFL v4.0.1, CTAL-TAE v2.0, CT-TAS v1.0, CT-AI v1.0) reveals that none of them defines the minimum required content for a textual endpoint description, despite recognising documentation quality as a measurable characteristic (FL-BO4). Existing research confirms the problem: Uddin and Robillard identified "incompleteness" as the most prevalent failure mode across API documentation, while Murphy et al. reported that specifications are "frequently missing, vague, or outdated" in real development teams. Machine-readable formats such as OpenAPI Specification address a different audience and assume technical knowledge of YAML or JSON, leaving the gap in informal human-readable documentation unresolved. The purpose of this study is to develop and validate the Minimal API Description Standard (MADS) - a structured 10-field template for plain-text API endpoint descriptions in corporate documentation tools - and to demonstrate its impact on software testing quality. MADS organises ten fields into four functional blocks: endpoint identification (HTTP method, URL pattern, operation name), input data (request parameters with types and constraints, request body), output data (successful response structure, error codes with conditions), and security context (authentication model, preconditions and business rules, API version). Fields are classified as mandatory or recommended. Each field is justified through convergent evidence from the scientific literature and practical security requirements (OWASP API Security Top 10). Empirical evaluation was conducted across three REST API endpoints of a typical order management service. Test cases were designed using two ISTQB-standard techniques: Boundary Value Analysis (BVA) and Equivalence Partitioning (EP). Three indicators were measured for both an unstructured description (UD) and a MADS-compliant description: the standard Requirement Coverage metric (RC, per ISTQB CTFL v4.0.1 section 5.3.1 and IEEE 829), the applicability of BVA and EP as a binary indicator per parameter, and the total number of test cases. Results show that RC increases from 23% (UD) to 100% (MADS), BVA/EP applicability rises from 25% to 100% of parameters, and the test case count grows from 5 to 26 — a 5.2-fold increase achieved exclusively through structured documentation - a 5.3-fold improvement achieved exclusively through structured documentation, without additional development resources. Response Code Coverage reached zero for all three endpoints under the unstructured condition, meaning negative test scenarios were entirely absent. The study further demonstrates that MADS serves as a structural prerequisite for reliable LLM-based test generation pipelines: structured MADS chunks improve RAG retrieval accuracy and enable deterministic resource access in Model Context Protocol (MCP) agentic architectures. The article proposes that the ISTQB Foundation Level Working Group consider incorporating minimum requirements for informal textual API descriptions into a future revision of the CTFL syllabus. Future research directions include automated MADS compliance validation, empirical correlation studies between MADS adoption and post-release defect rates, and extension of the standard to GraphQL and gRPC APIs.