Modern RESTful API DLs and frameworks for RESTful web services API schema modeling, documenting, visualizing

The given paper presents an overview of modern RESTful API description languages (belongs to interface description languages set) - OpenAPI, RAML, WADL, Slate - designed to provide a structured description of a RESTful web APIs (that is useful both to a human and for automated machine processing), with related RESTful web API modeling frameworks. We propose an example of the schema model of web API of the service for pre-trained distributional semantic models (word embeddings) processing. This service is a part of the Personal Research Information System services ecosystem - the Research and Development Workstation Environment class system for supporting research in the field of ontology engineering: the automated building of applied ontology in an arbitrary domain area as a main feature; scientific and technical creativity: the automated preparation of application documents for patenting inventions in Ukraine. It also presents a quick look at the relationship of Service-Oriented Architecture and Web services as well as REST fundamentals and RESTful web services; RESTful API creation process.

💡 Research Summary

The paper provides a comprehensive overview of modern RESTful API description languages (DLs) and the associated modeling frameworks, positioning them within the broader context of Service‑Oriented Architecture (SOA) and RESTful web services. It begins by outlining the evolution from traditional data exchange formats (XML, JSON) and SOAP‑based web services toward the more lightweight and scalable REST paradigm. The authors then discuss SOA, citing definitions from the Open Group and academic sources, emphasizing its focus on encapsulating business functionality as reusable services, supporting both synchronous and asynchronous (event‑driven) interaction models. A Venn diagram is used to illustrate the overlap and distinction between SOA and generic web services, underscoring that while web services can be employed within SOA, they are not synonymous.

The paper proceeds to detail the six constraints of the REST architectural style as defined by Fielding: client‑server separation, statelessness, cacheability, uniform interface (with its four sub‑constraints: resource identification, manipulation via representations, self‑descriptive messages, and hypermedia‑driven state transitions), layered system, and optional code‑on‑demand. By dissecting each constraint, the authors demonstrate how REST achieves simplicity, scalability, and evolvability, making it a natural fit for modern distributed systems.

The core contribution is a comparative analysis of four prominent RESTful API description languages: OpenAPI, RAML, WADL, and Slate. OpenAPI (formerly Swagger) is highlighted for its JSON/YAML syntax, extensive tooling ecosystem (code generators, interactive documentation, testing frameworks), and broad industry adoption. RAML, built on YAML and supporting Markdown, is presented as a design‑first language with strong visual tooling (API Designer) and a vendor‑neutral specification. WADL, an XML‑based alternative, is noted for its limited community support and declining relevance. Slate is described as a static documentation generator that excels at human‑readable presentation but does not provide a full machine‑readable contract. The authors enumerate the pros and cons of each, offering guidance on selection criteria such as ecosystem maturity, team expertise, and automation needs.

The paper then introduces an “APX” (Application Programming Experience) perspective on API creation, aligning it with typical product development stages: determining business value, selecting metrics, defining use cases, and finally designing the API schema. The schema is portrayed as a contract that can be consumed by both humans (documentation) and machines (code generation, automated testing).

To ground the discussion, the authors present a concrete case study: an API for a service that processes pre‑trained distributional semantic models (word embeddings). This service is part of the Personal Research Information System (PRIS) and supports the “Research and Development Workstation Environment,” which automates ontology construction and patent‑document generation for Ukrainian inventions. The paper supplies example specifications for key endpoints (e.g., GET /embeddings, POST /process, DELETE /embeddings/{id}) in both OpenAPI YAML and RAML formats, detailing parameters, response schemas, error handling, and security (OAuth2). This illustration demonstrates how a well‑defined schema directly maps to business logic and facilitates downstream tooling.

Finally, the authors propose an automated documentation and code‑generation pipeline leveraging tools such as Swagger UI, ReDoc, and Slate, integrated into CI/CD workflows. They stress the importance of versioning, backward compatibility, and continuous validation of the API contract. The conclusion reiterates that a solid understanding of REST constraints, combined with appropriate description language selection and robust modeling practices, enables developers and architects to build maintainable, interoperable, and user‑friendly APIs in today’s service‑centric ecosystems.