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), w...
Gespeichert in:
| Datum: | 2019 |
|---|---|
| Hauptverfasser: | , , |
| Format: | Artikel |
| Sprache: | English |
| Veröffentlicht: |
Інститут програмних систем НАН України
2019
|
| Schlagworte: | |
| Online Zugang: | https://pp.isofts.kiev.ua/index.php/ojs1/article/view/335 |
| Tags: |
Tag hinzufügen
Keine Tags, Fügen Sie den ersten Tag hinzu!
|
| Назва журналу: | Problems in programming |
Institution
Problems in programming| id |
pp_isofts_kiev_ua-article-335 |
|---|---|
| record_format |
ojs |
| resource_txt_mv |
ppisoftskievua/10/4bbf78ed512bb99c6d311edef79b6f10.pdf |
| spelling |
pp_isofts_kiev_ua-article-3352019-02-28T11:40:40Z Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing Современные языки описания веб-сервисов и фреймворки для их моделирования, документирования, визуализации Сучасні мови опису веб-сервісів та фреймворки для їх моделювання, документування, візуалізаціїї Malakhov, K.S. Kurgaev, A.P. Velychko, V.Yu. Service-Oriented Architecture; Web service; REST; RESTful API; OpenAPI; RAML; WADL; Slate UDC 004.724, 004.62 cервис-ориентированная архитектура; веб-сервис; REST; RESTful API; OpenAPI; RAML; WADL; Slate УДК 004.724, 004.62 сервіс-орієнтована архітектура; веб-сервіс; REST; RESTful API; OpenAPI; RAML; WADL; Slate УДК 004.724, 004.62 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 modelling 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.Problems in programming 2018; 4: 59-68 В статье представлен обзор и сравнительный анализ современных языков описания веб-сервисов – OpenAPI, RAML, WADL, Slate – которые предназначены для представления структурированного описания современных веб-сервисов (веб-API) и разработаны с учетом применения как для их автоматизированной обработки описаний программными приложениями, так и для восприятия разработчиками программного обеспечения. Разработана модель (схема) веб-API сервиса процессинга предобученных дистрибутивно-семантических моделей, который является частью экосистемы сервисов "Персональной научно-исследовательской информационной системы" – системы класса Автоматизированное рабочее место научных исследований АРМ-НИ поддержки научно-технического творчества и исследований в области онтологического инжиниринга. Приведен короткий обзор современного положения веб-сервисов в составе Сервис-ориентированной архитектуры и на их взаимодействия. Также представлена методика описания веб сервисов при помощи современного языка структурного описания взаимодействия интерфейсов сервисов.Problems in programming 2018; 4: 59-68 Бази даних, веб-сайти, веб-застосунки, бізнес-орієнтоване програмне забезпечення та сервіси повинні обмінюватися даними. Це досягається шляхом визначення стандартних форматів даних, таких як розширювана мова розмітки XML, або запис об’єктів JavaScript JSON, а також протоколів передачі даних або веб-сервісів, таких як Простий протокол доступу до об'єктів SOAP або більш популярний сьогодні –"передача репрезентативного стану" REST. Розробникам часто доводиться розробляти свої власні інтерфейси прикладного програмування застосунків API, щоб працювати з застосунками, інтегруючи певну бізнес-логіку навколо операційних систем або серверів. В статті наведено огляд сучасних мов опису веб-сервісів – OpenAPI, RAML, WADL, Slate – які призначені для подання структурованого опису сучасних веб-сервісів (веб-API), як для їх автоматизованої обробки програмними застосунками, так і для сприйняття розробником програмного забезпечення. Розроблено модель (схему) веб-API сервісу процесінгу дистрибутивно-семантичних моделей, який є частиною екосистеми сервісів "Персональної науково-дослідницької інформаційної системи" – системи класу Автоматизоване робоче місце наукових досліджень АРМ-НД підтримки науково-технічної творчості та досліджень в області онтологічного інжинірингу.Представлено короткий погляд на сучасне становище веб-сервісів в складі Сервіс-орієнтованої архітектури та на їх взаємодію. Також представлена методика опису веб-сервісів за допомогою сучасної мови структурного опису взаємодії інтерфейсів сервісів.Problems in programming 2018; 4: 59-68 Інститут програмних систем НАН України 2019-02-28 Article Article application/pdf https://pp.isofts.kiev.ua/index.php/ojs1/article/view/335 10.15407/pp2018.04.059 PROBLEMS IN PROGRAMMING; No 4 (2018); 59-68 ПРОБЛЕМЫ ПРОГРАММИРОВАНИЯ; No 4 (2018); 59-68 ПРОБЛЕМИ ПРОГРАМУВАННЯ; No 4 (2018); 59-68 1727-4907 10.15407/pp2018.04 en https://pp.isofts.kiev.ua/index.php/ojs1/article/view/335/335 Copyright (c) 2018 PROBLEMS OF PROGRAMMING |
| institution |
Problems in programming |
| baseUrl_str |
https://pp.isofts.kiev.ua/index.php/ojs1/oai |
| datestamp_date |
2019-02-28T11:40:40Z |
| collection |
OJS |
| language |
English |
| topic |
Service-Oriented Architecture Web service REST RESTful API OpenAPI RAML WADL Slate UDC 004.724 004.62 |
| spellingShingle |
Service-Oriented Architecture Web service REST RESTful API OpenAPI RAML WADL Slate UDC 004.724 004.62 Malakhov, K.S. Kurgaev, A.P. Velychko, V.Yu. Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| topic_facet |
Service-Oriented Architecture Web service REST RESTful API OpenAPI RAML WADL Slate UDC 004.724 004.62 cервис-ориентированная архитектура веб-сервис REST RESTful API OpenAPI RAML WADL Slate УДК 004.724 004.62 сервіс-орієнтована архітектура веб-сервіс REST RESTful API OpenAPI RAML WADL Slate УДК 004.724 004.62 |
| format |
Article |
| author |
Malakhov, K.S. Kurgaev, A.P. Velychko, V.Yu. |
| author_facet |
Malakhov, K.S. Kurgaev, A.P. Velychko, V.Yu. |
| author_sort |
Malakhov, K.S. |
| title |
Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_short |
Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_full |
Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_fullStr |
Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_full_unstemmed |
Modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_sort |
modern restful api dls and frameworks for restful web services api schema modeling, documenting, visualizing |
| title_alt |
Современные языки описания веб-сервисов и фреймворки для их моделирования, документирования, визуализации Сучасні мови опису веб-сервісів та фреймворки для їх моделювання, документування, візуалізаціїї |
| description |
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 modelling 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.Problems in programming 2018; 4: 59-68 |
| publisher |
Інститут програмних систем НАН України |
| publishDate |
2019 |
| url |
https://pp.isofts.kiev.ua/index.php/ojs1/article/view/335 |
| work_keys_str_mv |
AT malakhovks modernrestfulapidlsandframeworksforrestfulwebservicesapischemamodelingdocumentingvisualizing AT kurgaevap modernrestfulapidlsandframeworksforrestfulwebservicesapischemamodelingdocumentingvisualizing AT velychkovyu modernrestfulapidlsandframeworksforrestfulwebservicesapischemamodelingdocumentingvisualizing AT malakhovks sovremennyeâzykiopisaniâvebservisovifrejmvorkidlâihmodelirovaniâdokumentirovaniâvizualizacii AT kurgaevap sovremennyeâzykiopisaniâvebservisovifrejmvorkidlâihmodelirovaniâdokumentirovaniâvizualizacii AT velychkovyu sovremennyeâzykiopisaniâvebservisovifrejmvorkidlâihmodelirovaniâdokumentirovaniâvizualizacii AT malakhovks sučasnímoviopisuvebservísívtafrejmvorkidlâíhmodelûvannâdokumentuvannâvízualízacííí AT kurgaevap sučasnímoviopisuvebservísívtafrejmvorkidlâíhmodelûvannâdokumentuvannâvízualízacííí AT velychkovyu sučasnímoviopisuvebservísívtafrejmvorkidlâíhmodelûvannâdokumentuvannâvízualízacííí |
| first_indexed |
2025-07-17T09:45:01Z |
| last_indexed |
2025-07-17T09:45:01Z |
| _version_ |
1838409303364468736 |
| fulltext |
Моделі та засоби систем баз даних і знань
© Kyrylo Malakhov, Aleksandr Kurgaev, Vitalii Velychko, 2018
ISSN 1727-4907. Проблеми програмування. 2018. № 4 59
UDC 004.724, 004.62 https://doi.org/10.15407/pp2018.04.059
Kyrylo Malakhov, Aleksandr Kurgaev, Vitalii Velychko
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 modelling frameworks. We propose an example of the schema model of web API of the
service for pre-trained distributional semantic models (word embedding’s) 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 au-
tomated 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.
Key words: Service-Oriented Architecture, Web service, REST, RESTful API, OpenAPI, RAML, WADL,
Slate.
Introduction
Databases, web sites, business applica-
tions and services need to exchange data. This
is accomplished by defining standard data
formats such as Extensible Markup Language
(XML) or JavaScript Object Notation
(JSON), as well as transfer protocols or Web
services such as the Simple Object Access
Protocol (SOAP) or the more popular today –
Representational State Transfer (REST). De-
velopers often have to design their own Ap-
plication Programming Interfaces (APIs) to
make applications work while integrating
specific business logic around operating sys-
tems, or servers. This paper introduces these
concepts with a focus on the RESTful APIs
and presents an overview of modern RESTful
API description languages (RESTful API
DLs): OpenAPI Specification, RAML, and
the example of modeling the schema of web
API of the service for pre-trained distribu-
tional semantic models (word embeddings)
processing (is a part of the “Personal Re-
search Information System” [1] services eco-
system – the “Research and Development
Workstation Environment” [2] class system
for supporting research in the field of ontolo-
gy engineering: the automated building of ap-
plied ontology in an arbitrary domain area as
a main feature; scientific and technical crea-
tivity: the automated preparation of applica-
tion documents for patenting inventions in
Ukraine) with related RESTful web API
modelling frameworks.
Service-Oriented Architecture style
and Web services
According to the Open Group [3] (a
global consortium that develops open, ven-
dor-neutral information technology stand-
ards), an SOA is an architectural style that
supports service orientation. Service orienta-
tion is a way of thinking in terms of the out-
comes of services, and how they can be de-
veloped and combined. In this definition, a
service is a repeatable business activity that
can be logically represented; the Open Group
gives the examples: “check customer credit,”
and “provide weather data.” Further, a service
is self-contained, may be composed of other
services, and consumers of the service treat
the service as a black box. SOA is a distinct
architectural style which is a major improve-
ment over earlier ideas, although it includes
some of the earlier ideas. Also, traditional ar-
chitectural methods must be employed in or-
der to obtain maximum benefit from using
SOA.
http://dx.doi.org/10.7124/bc.000027
Моделі та засоби систем баз даних і знань
60
Another definition of Service-Oriented
Architecture comes from [4]: a paradigm for
organizing and utilizing distributed capabili-
ties that may be under the control of different
ownership domains. It provides a uniform
means to offer, discover, interact with and use
capabilities to produce desired effects con-
sistent with measurable preconditions and ex-
pectations. According to [4], the focus of
SOAs is to perform a task (business function).
This is different from some other paradigms,
such as object-oriented architectures, where
the focus is more on structure of the solution
in the case of an object-oriented architecture,
the focus is on how to package data inside an
object. SOAs address ownership boundaries
through service descriptions and service inter-
faces. SOA provides reuse of externally de-
veloped frameworks by providing easy in-
teroperability between systems. Generally
speaking, in order to perform a task, an SOA
groups services on different systems, possibly
running on different operating systems, possi-
bly written using different programming lan-
guages. Most current SOA-based applications
employ an asynchronous client/server-type
architectural style – asynchronous event-
driven architectural style [5]. Event-driven
SOA (also known as SOA 2.0) is the current
and advanced form of SOA. In this approach
at present, unlike the older SOA approach
where services used to be designed as pre-
defined processes, the events generally trigger
the execution of activities. The asynchronous
event-driven architectural style is better for
real time or proactive systems, since business
processes are treated as a sequence of events,
and therefore different business processes that
have little relationship with each other, except
for a few individual shared tasks, do not have
to obey the same kind of centralized man-
agement. In an asynchronous event-driven
architecture, an event message carries a state
change to an event server. The event server
passes these events along to the servers, pos-
sibly with value added. Servers may then
generate messages for other event servers (of-
ten calls “publish/subscribe” architecture).
More detailed in-depth look at the current
state of SOA presented in [6, 7].
Figure 1 uses a Venn diagram to illus-
trate the relationship between SOA and Web
services. The overlapping area in the center
represents SOA using Web services for con-
nections. The nonoverlapping area of Web
services represents that Web services can be
used for connections, but connections alone
do not make for an SOA. The non-
overlapping area of SOA indicates that an
SOA can use Web services as well as connec-
tions other than Web services (the original
specifications of CORBA and DCOM are ex-
amples).
Figure 1. Relationship of Web services
and SOA
Key to SOA is the identification and
design of services. The idea is that services
should be designed in such a way that they
become components that can be assembled in
multiple ways to support or automate business
functions. It is not necessarily easy to proper-
ly identify and design services. When done
well, the services allow an organization to
quickly assemble services – or modify the as-
sembly of services – of add or modify the sup-
port or automation of business functions. Here
are basic concepts related to services [8].
Atomic service. An atomic service
is a well-defined, self-contained function that
does not depend on the context or state of
other services. Generally, an atomic service
would be seen as fine grained or having a fin-
er granularity.
Composite service. A composite
service is an assembly of atomic or other
composite services. The ability to assemble
Моделі та засоби систем баз даних і знань
61
services is referred to as composability. Com-
posite services are also referred to as com-
pound services. Generally, a composite ser-
vice would be seen as coarse grained or hav-
ing a larger granularity.
Loosely coupled. This is a design
concept where the internal workings of one
service are not “known” to another service.
All that needs to be known is the external be-
havior of the service. This way, the underly-
ing programming of a service can be modified
and, as long as external behavior has not
changed, anything that uses that service con-
tinues to function as expected. This is similar
to the concept of information hiding that has
been used in computer science for a long
time.
The design challenge is to find a bal-
ance between fine-grained and coarse-grained
services to minimize communication over-
head yet keep the services loosely coupled.
Services are assembled to support or
automate business functions. Figure 2 illus-
trates the assembly of services. This repre-
sents an SOA. Web services are used to con-
nect the services in an SOA [8].
Figure 2. Assembly of services into an SOA
It is easy to imagine that we can reas-
semble the same services with other services
to achieve a different functionality. This abil-
ity to change the assembly of services is one
way that an SOA can quickly adapt to chang-
ing business needs.
RESTful architectural style and
RESTful web services
According to Fielding [9], the REST-
ful architectural style focuses on: “...the roles
of components, the constraints upon their in-
teraction with other components, and their
interpretation of significant data elements...”.
He coined the term “REST” an architectural
style for distributed hypermedia systems. Put
simply, REST (short for Representational
State Transfer) is an architectural style de-
fined to help create and organize distributed
systems. The key word from that definition
should be “style,” because an important as-
pect of REST is that it is an architectural style
– not a guideline, not a standard, or anything
that would imply that there are a set of hard
rules to follow in order to end up having a
RESTful architecture.
The RESTful architectural style con-
sists of constraints on data, constraints on the
interpretation of data, constraints on compo-
nents, and constraints on connectors between
components.
The RESTful architectural style pos-
sesses the following constraints [9].
Client-Server. The separation of con-
cerns is the core theme of the Web’s client-
server constraints. The Web is a client-server-
based system, in which clients and servers
have distinct parts to play. They may be im-
plemented and deployed independently, using
any language or technology, so long as they
conform to the Web’s uniform interface.
Stateless. The client-server interaction
is stateless. There is no stored context on the
server. Any session information must be kept
by the client.
Cacheable. Data in a response (a re-
sponse to a previous request) is labeled as
cacheable or non-cacheable. If it is cacheable,
the client (or an intermediary) may reuse that
for the same kind of request in the future.
Caching response data can help to reduce cli-
ent-perceived latency, increase the overall
availability and reliability of an application,
and control a web server’s load. In a word,
caching reduces the overall cost of the Web.
Uniform Interface. There is a uniform
interface between components. In practice,
there are four interface constraints: resource
identification – requests identify the resources
they are operating on (by a URI, for exam-
ple); resource manipulation through the repre-
sentation of the resource – when a client or
server that has access to a resource, it has
enough information based on understanding
Services
Web services
Моделі та засоби систем баз даних і знань
62
the representation of the resource to be able to
modify that resource; messages are self-
descriptive – the message contains enough
information to allow a client or server to han-
dle the message, this is normally done
through the use of Internet Media types
(MIME types); use of hypermedia to change
the state of the application – for example, the
server provides hyperlinks that the client uses
to make state transitions.
Layered System. Components are or-
ganized in hierarchical layers; the compo-
nents are only aware of the layer within which
the interaction is occurring. Thus, a client
connecting to a server is not aware of any in-
termediate connections.
Code-on-Demand. The Web makes
heavy use of code-on-demand, a constraint
which enables web servers to temporarily
transfer executable programs, such as scripts
or plug-ins, to clients. Code-on-demand tends
to establish a technology coupling between
web servers and their clients, since the client
must be able to understand and execute the
code that it downloads on-demand from the
server. For this reason, code-on-demand is the
only constraint of the Web’s architectural
style that is considered optional.
So, it’s pretty clear that the RESTful
web services meet the constraints of the
RESTful architecture. Summarizing, a REST-
ful web service is client/server-based, does
not store state. It accesses resources (web
pages or data) located at a URL. The results
of a request from client to server can be
cached in the client. It has a uniform interface
with self-descriptive messages, based on hy-
permedia. Also, the client and server aren’t
aware of intermediate connections between
the two of them.
RESTful API creation process –
designing API and creating
a schema modeling
As UI is to UX (User Experience),
API is to APX (Application Programming
Experience). Like optimizing for UX (User
Experience) has become a primary concern in
UI development, also optimizing for APX
(API User Experience) should be a primary
concern in API development.
The process of RESTful API creation
must contain all of the following steps:
Determining business value.
Choosing metrics.
Defining use cases.
Designing API and creating a
schema model.
A detailed description of the RESTful
API creation process is presented in [8, 10,
11]. In our paper we will focus on the design-
ing API and creating a schema model. Model-
ing the schema for your API means creating a
design document that can be shared with oth-
er teams, customers, or executives. A schema
model is a contract between your organization
and the clients who will be using it. A schema
model is essentially a contract describing
what the API is, how it works, and exactly
what the endpoints are going to be. Think of it
as a map of the API, a user-readable and a
machine-readable (automated machine pro-
cessing) description of each endpoint, which
can be used to discuss the API before any
code is written. With a schema model, we can
ensure that everyone has a shared understand-
ing of what the API will do and how each re-
source will be represented when the API is
complete. Each of the schema modeling lan-
guages has tools available to automate testing
or code creation based on the schema model
you’ve created. But even without this func-
tionality, the schema model helps us have a
solid understanding of the API before a single
line of code is written. Figure 3 shows the
API Modeling framework where you have
API specifications defined and generate API
documentation [12]. Also, generate server and
client source code.
Next, we’ll look at the specifics of two
of the main schema modeling frameworks and
markup languages:
RESTful API Modeling Language
(RAML), which supports Markdown.
OpenAPI specification (OpenAPI)
format (previously Swagger), which supports
JSON and YAML.
Моделі та засоби систем баз даних і знань
63
Figure 3. API modelling
RAML and OpenAPI: an overview
The RESTful API Modeling Language
(RAML) [13] is a concise, expressive lan-
guage for describing RESTful APIs. Built on
broadly used standards such as YAML
(YAML stands for Yet Another Markup Lan-
guage, and is a generic specification lan-
guage) and JSON, RAML is a non-prop-
rietary, vendor-neutral open spec. RAML was
created around the notion of design-first de-
velopment [12]. Although all of the specifica-
tion languages can be used this way, RAML
was designed this way from the outset. It
makes it easy to create a code development
life cycle that supports the development of
APIs that meet your business goals and use
cases. The RAML website [14] has good doc-
umentation, including strategies, best practic-
es, and practical instruction. You’ll find a
basic tutorial for the RAML language itself at
[14]. RAML has good online modeling tools,
also, it has been open-sourced along with
tools and parsers for common languages. The
development of RAML will be overseen by a
steering committee of API and UX practition-
ers, and there is an emerging ecosystem of
third-party tools being developed around
RAML [15]. Consider the pros and cons of
RAML [16]. Pros: single specification to
maintain; strong, visual-based integrated de-
velopment environment and online tooling
with collaboration focus; allows for design
patterns; easy to get started. Cons: lacks
strong documentation and tutorials outside of
specification; limited code reuse/extensions;
multiple specifications required for several
tools, including dev and QA; poor tooling
support for newer versions.
The best way to get started with
RAML is to use the RAML API Designer
with free account on the Anypoint system,
where MuleSoft maintains its RAML specif-
ic tools [17]. RAML excels at supporting the
entire API's lifecycle. It provides a balance
between developer tooling and technical
writers without taking away from one or the
other. It also is the fastest framework to
ramp up your project. MuleSoft maintains
some open source tools that can extend and
improve experience with a RAML specifica-
tion. The API Designer that helps you design
your schema from the ground up. An API
Console graphical user interface is available
that displays the structure and patterns and
creates interactive documentation. The API
Notebook provides a way to use JavaScript
to test and explore APIs and create Mark-
down versions of the API to share on
GitHub. You’ll find hundreds of additional
Client
Source
Server
Source
JSON,
YAML
HTML
REST client
RESTful Web service
API
specification
(machine-readable)
API
documentation,
visualising
(human-readable)
Generate API specification
Generate client source
Generate server so
urce
Generate API documentation
Generate
API documentation
Моделі та засоби систем баз даних і знань
64
RAML tools at GitHub and on the [13] web-
site, which can help you create and leverage
the schemas you build.
The OpenAPI Specification OpenAPI,
originally known as the Swagger Specifica-
tion, is a specification for machine-readable
interface files for describing, producing, con-
suming, and visualizing RESTful web ser-
vices. Originally part of the Swagger frame-
work [18], it became a separate project in
2016, overseen by the OpenAPI Initiative, an
open source collaborative project of the Linux
Foundation [19]. Swagger and some other
tools can generate code, documentation and
test cases given an interface file. OpenAPI
was one of the earliest schema modeling
frameworks available, and it has gone through
a few revisions. Version 3.0 is the most recent
one as of this writing. During the develop-
ment of the various versions, they’ve incorpo-
rated many of the best practices uncovered by
the other two languages, and OpenAPI re-
mains one of the innovative frameworks
available. OpenAPI supports both JSON and
YAML for its schema markup. Consider the
pros and cons of OpenAPI [16]. Pros: a large
community and support-base; high adoption
rate, meaning lots of documentation; strong
framework support; has the largest language
support of any opensource framework. Cons:
requires multiple specifications for some
tools, including dev and QA; doesn't allow for
code reuse, includes, or extensions; lacks
strong developer tools; requires schemas for
all responses.
OpenAPI has a very strong modeling
language for defining exactly what’s expected
of the system – very useful for testing and
creating coding stubs for a set of APIs.
In comparison to one another, both
OpenAPI and RAML are very capable, com-
patible with many languages.
Both offer compatibility in: .NET,
Go, Haskell, Java, JavaScript, Node.js, PHP,
Python, Ruby, Scala.
OpenAPI’s additional capabilities:
Clojure, Coldfusion, D, Eiffel, Erlang,
Groovy, and Typescript.
RAML's additional capabilities:
Elixer and Pearl.
Both languages are strong and able
to produce excellent APIs despite their dif-
ferences. Their key differences are what can
help you determine which is best for your
business.
OpenAPI’s best features are its strong
documentation and compatibility with lesser
used languages. It provides a fast setup and a
large support community. The big takeaway
for OpenAPI is that it is designed as a bot-
tom-up specification. OpenAPI specifies the
behavior which affects the API to create more
complex, interlocking systems.
RAML excels at supporting the entire
API’s lifecycle. It provides a balance between
developer tooling and technical writers with-
out taking away from one or the other. It also
is the fastest framework to ramp up your pro-
ject. The main difference between the two is
that RAML is a top-down specification,
meaning it breaks down the system and ex-
plains the behavior of the various sub-
components.
The main characteristics of both
RESTful API DLs are presented in the com-
parative table.
There are, of course, alternatives. Two
of the most popular are WADL [20] and Slate
[21]. Each have their own caveats, of course.
WADL is incredibly time consuming to create
descriptions with, and the linking methodolo-
gy leaves much to be desired when compared
to any of the three specifications discussed
throughout this article. Slate, similarly, has
the caveat of having untested or unproven ap-
proaches due to the relatively small userbase,
despite the fact that it handles documentation
much like API Blueprint [22] does, and gen-
erates a pretty interface for it all.
These alternatives are interesting, to
be sure, but their low adoption rates, issues
inherent to their structure, and fundamental
caveats make a potentially unstable bet. With
many strategies in the modern IT workforce
focusing heavily on rapid development and
deployment, untested approaches have the
distinct possibility of massively lowered qual-
ity as the demand rises exponentially.
As part of the development of the
“Personal Research Information System”
[1, 2], the API schemas of its services was
Моделі та засоби систем баз даних і знань
65
Table. Сomparison of modern RESTful API DLs and frameworks
Description
Language
RAML OpenAPI WADL Slate
Software
license
Apache 2.0 Apache 2.0 CDDL 1.1 Apache 2.0
Format
YAML
(Markdown)
YAML, JSON XML Markdown
Open source yes yes yes yes
Commercial
offering
yes yes no no
Sponsored by
Mulesoft, Cisco,
VMware, Paypal,
AngularJS, Box
Open API Initia-
tive, Google, IBM,
Mcrosoft
Oracle -
Current release 1.0 3.0 - 2.3.1
Design
strategy
API-first Existing API Existing API Existing API
References http://raml.org http://swagger.io
https://github.com
/javaee/wadl
https://github.com
/lord/slate
Code
generation
yes yes no no
Documentation yes yes yes yes
Visual-based
IDE
yes yes no yes
Online IDE yes yes no no
Editors
API Workbench
(IDE based on
Atom)
Swagger Tools
(editor, codegen,
UI)
no Local web editor
modeled with OpenAPI, in particular, the
schema model of web API of the service for
pre-trained distributional semantic models
(word embeddings) (DSM) processing. With
this web service API is possible to: calculate
semantic similarity between pair of terms (in-
cluding multiple-word terms, one-word terms,
words) within the chosen DSM; compute a
list of nearest semantic associates for terms
(including multiple-word terms, one-word
terms, words) within the chosen DSM; find
the center of lexical cluster for a set of terms
(including multiple-word terms, one-word
terms, words) within the chosen DSM; calcu-
late semantic similarity between two sets of
terms (including multiple-word terms, one-
word terms, words) within the chosen DSM.
The source code and the service API
schema model description are available via
GitHub repository [23].
https://github.com/
https://github.com/
Моделі і засоби систем баз даних та знань
66
Conclusion
OpenAPI as well as RAML have very
much in common. Projects relying on the ex-
tensive language support and tool integrations
will tend to OpenAPI. But if the language
support is not crucial as implementations are
foremost done in standard languages such as
Java, RAML is an equivalent option. OpenA-
PI and RAML both have a large community
and are backed by market leaders, so it will
never be wrong choosing one of them for API
documentation.
Recently, several APIs contributors
(members of 3Scale, Apigee, Capital One,
Google, IBM, Intuit, Microsoft, PayPal,
Restlet and SmartBear) have announced the
Open API Initiative [19], which aims at
standardizing the way REST APIs are de-
scribed. This initiative will extend the Swag-
ger specification and format to create an open
technical community where members can eas-
ily contribute to building a vendor-neutral,
portable and open specification for providing
metadata for RESTful APIs. We hope this
initiative will also promote and facilitate the
adoption and use of a standard API Descrip-
tion Language.
References
1. Palagin O.V., Velychko V.Yu., Malakhov
K.S. and Shchurov O.S. Personal research in-
formation system. About developing the
methods for searching patent analogs of in-
vention. Computer means, networks and sys-
tems. 2017. N 16. P. 5–13. (in Ukrainian).
2. Palagin O.V., Velychko V.Yu., Malakhov
K.S. and Shchurov O.S. (2018). Research and
development workstation environment: the
new class of current research information sys-
tems. Problems in programming. N 2–3. P.
289–298.
3. Open Group. Service Oriented Architecture:
What is SOA? [Online] Available from:
https://www.opengroup.org/soa/source-book/
soa/p1.htm [Accessed: 05.11.2018]
4. Mackenzie C.M., Laskey K., McCabe F.,
Brown P.F., Metz R. 2006. OASIS Reference
Model for Service Oriented Architecture 1.0.
OASIS. [Online] Available from:
https://www.oasis-open.org/committees/
download.php/19679/soa-rm-cs.pdf [Ac-
cessed: 05.11.2018]
5. Chou D. Using Events in Highly Distributed
Architectures. The Architecture Journal. [On-
line] Available from: https://msdn.microsoft.
com/en-us/library/ dd129913.aspx [Accessed:
05.11.2018]
6. Bhowmik S. Cloud Computing. Cambridge
University Press. 2017. 462 p.
7. Etzkorn L.H. Introduction to Middleware:
Web Services, Object Components, and Cloud
Computing. CRC Press, 2017. 662 p.
8. Barry D.K. Web Services, Service-Oriented
Architectures, and Cloud Computing: The
Savvy Manager’s Guide. Morgan Kaufmann
is an imprint of Elsevier, 2013. 248 p.
9. Fielding R. 2000. Architectural Styles and the
Design of Network-Based Software Architec-
tures. Ph.D. Disser- tation, University of Cali-
fornia-Irvine. [Online] Avaliable from:
https://www.ics.uci.edu/~fielding/pubs/dissert
ation/top.htm [accessed 05.11.2018]
10. Pereira C.R. Building APIs with Node.js.
Apress, 2016. 135 p.
11. Doglio F. REST API Development with
Node.js. Apress, 2018. 323 p.
12. Patni S. Pro RESTful APIs: Design, Build and
Integrate with REST, JSON, XML and JAX-
RS. Apress, 2017. 126 p.
13. RESTful API Modeling Language (RAML).
[Online] Available from: https://raml.org/
[Accessed: 05.11.2018]
14. RAML 100 Tutorial | RAML. [Online] Avail-
able from: https://raml.org/developers/raml-
100-tutorial [Accessed: 05.11.2018]
15. API Design Tooling From RAML. [Online]
Available from:
http://apievangelist.com/2014/ 03/01/api-
design-tooling-from-raml/ [Accessed:
05.11.2018]
16. Swagger (OAS) vs. RAML - Which is Better
for Building APIs? [Online] Available from:
https://blog.vsoftconsulting.com/blog/is-raml-
or-swagger-better-for-building-apis [Ac-
cessed: 05.11.2018]
17. Anypoint Platform. [Online] Available from:
https://anypoint.mulesoft.com/ [Accessed:
05.11.2018]
18. The Best APIs are Built with Swagger Tools |
Swagger. [Online] Available from:
https://swagger.io/ [Accessed: 05.11.2018]
19. OpenAPI Initiative Charter. [Online] Availa-
ble from: https://www.openapis.org/partici-
pate/how-to-contribute/governance [Ac-
cessed: 05.11.2018]
https://www.opengroup.org/soa/source-book/%20soa/p1.htm
https://www.opengroup.org/soa/source-book/%20soa/p1.htm
https://www.oasis-open.org/committees/%20download.php/19679/soa-rm-cs.pdf
https://www.oasis-open.org/committees/%20download.php/19679/soa-rm-cs.pdf
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
https://raml.org/
https://raml.org/developers/raml-100-tutorial
https://raml.org/developers/raml-100-tutorial
http://apievangelist.com/2014/%2003/01/api-design-tooling-from-raml/
http://apievangelist.com/2014/%2003/01/api-design-tooling-from-raml/
https://blog.vsoftconsulting.com/blog/is-raml-or-swagger-better-for-building-apis
https://blog.vsoftconsulting.com/blog/is-raml-or-swagger-better-for-building-apis
https://anypoint.mulesoft.com/
https://swagger.io/
https://www.openapis.org/participate/how-to-contribute/governance
https://www.openapis.org/participate/how-to-contribute/governance
Моделі і засоби систем баз даних та знань
67
20. Web Application Description Language.
[Online] Available from: https://www.w3.org/
Submission/wadl/ [Accessed: 05.11.2018]
21. Lord/slate: Beautiful static documentation for
your API. [Online] Available from:
https://github.com/lord/slate [Accessed:
05.11.2018]
22. API Blueprint | API Blueprint. [Online]
Available from: https://apiblueprint.org/ [Ac-
cessed: 05.11.2018]
23. Malakhovks/ds-rest-api. GitHub. [Online]
Available from: https://github.com/mala-
khovks/ds-rest-api [Accessed: 05.11.2018]
Література
1. Палагін О.В., Величко В.Ю., Малахов К.С.,
Щуров О.С. Автоматизоване робоче місце
наукового дослідника. До питання розроб-
ки методів пошуку аналогів патентної до-
кументації винаходу. Комп'ютерні засоби,
мережі та системи. 2017. № 16. С. 5–13.
2. Palagin O.V., Velychko V.Yu., Malakhov
K.S. and Shchurov O.S. (2018). Research and
development workstation environment: the
new class of current research information sys-
tems. Problems in programming. N 2–3.
P. 289–298.
3. Open Group. Service Oriented Architecture:
What is SOA? [Online] Available from:
https://www.opengroup.org/soa/source-book/
soa/p1.htm [Accessed: 05.11.2018]
4. Mackenzie C.M., Laskey K., McCabe F.,
Brown P.F., Metz R. 2006. OASIS Reference
Model for Service Oriented Architecture 1.0.
OASIS. [Online] Available from:
https://www.oasis-open.org/committees/
download.php/19679/soa-rm-cs.pdf [Ac-
cessed: 05.11.2018]
5. Chou D. Using Events in Highly Distributed
Architectures. The Architecture Journal. [On-
line] Available from: https://msdn.microsoft.
com/en-us/library/ dd129913.aspx [Accessed:
05.11.2018]
6. Bhowmik S. Cloud Computing. Cambridge
University Press. 2017. 462 p.
7. Etzkorn L.H. Introduction to Middleware:
Web Services, Object Components, and Cloud
Computing. CRC Press, 2017. 662 p.
8. Barry D.K. Web Services, Service-Oriented
Architectures, and Cloud Computing: The
Savvy Manager’s Guide. Morgan Kaufmann
is an imprint of Elsevier, 2013. 248 p.
9. Fielding R. 2000. Architectural Styles and the
Design of Network-Based Software Architec-
tures. Ph.D. Disser- tation, University of Cali-
fornia-Irvine. [Online] Avaliable from:
https://www.ics.uci.edu/~fielding/pubs/dissert
ation/top.htm [accessed 05.11.2018]
10. Pereira C.R. Building APIs with Node.js.
Apress, 2016. 135 p.
11. Doglio F. REST API Development with
Node.js. Apress, 2018. 323 p.
12. Patni S. Pro RESTful APIs: Design, Build and
Integrate with REST, JSON, XML and JAX-
RS. Apress, 2017. 126 p.
13. RESTful API Modeling Language (RAML).
[Online] Available from: https://raml.org/
[Accessed: 05.11.2018]
14. RAML 100 Tutorial | RAML. [Online] Avail-
able from: https://raml.org/developers/raml-
100-tutorial [Accessed: 05.11.2018]
15. API Design Tooling From RAML. [Online]
Available from:
http://apievangelist.com/2014/ 03/01/api-
design-tooling-from-raml/ [Accessed:
05.11.2018]
16. Swagger (OAS) vs. RAML - Which is Better
for Building APIs? [Online] Available from:
https://blog.vsoftconsulting.com/blog/is-raml-
or-swagger-better-for-building-apis [Ac-
cessed: 05.11.2018]
17. Anypoint Platform. [Online] Available from:
https://anypoint.mulesoft.com/ [Accessed:
05.11.2018]
18. The Best APIs are Built with Swagger Tools |
Swagger. [Online] Available from:
https://swagger.io/ [Accessed: 05.11.2018]
19. OpenAPI Initiative Charter. [Online] Availa-
ble from: https://www.openapis.org/partici-
pate/how-to-contribute/governance [Ac-
cessed: 05.11.2018]
20. Web Application Description Language.
[Online] Available from: https://www.w3.org/
Submission/wadl/ [Accessed: 05.11.2018]
21. Lord/slate: Beautiful static documentation for
your API. [Online] Available from:
https://github.com/lord/slate [Accessed:
05.11.2018]
22. API Blueprint | API Blueprint. [Online]
Available from: https://apiblueprint.org/ [Ac-
cessed: 05.11.2018]
23. Malakhovks/ds-rest-api. GitHub. [Online]
Available from: https://github.com/mala-
khovks/ds-rest-api [Accessed: 05.11.2018]
Data received 20.09.2018
https://www.w3.org/%20Submission/wadl/
https://www.w3.org/%20Submission/wadl/
https://github.com/lord/slate
https://apiblueprint.org/
https://github.com/malakhovks/ds-rest-api
https://github.com/malakhovks/ds-rest-api
javascript:void(0)
javascript:void(0)
javascript:void(0)
javascript:void(0)
https://www.opengroup.org/soa/source-book/%20soa/p1.htm
https://www.opengroup.org/soa/source-book/%20soa/p1.htm
https://www.oasis-open.org/committees/%20download.php/19679/soa-rm-cs.pdf
https://www.oasis-open.org/committees/%20download.php/19679/soa-rm-cs.pdf
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
https://raml.org/
https://raml.org/developers/raml-100-tutorial
https://raml.org/developers/raml-100-tutorial
http://apievangelist.com/2014/%2003/01/api-design-tooling-from-raml/
http://apievangelist.com/2014/%2003/01/api-design-tooling-from-raml/
https://blog.vsoftconsulting.com/blog/is-raml-or-swagger-better-for-building-apis
https://blog.vsoftconsulting.com/blog/is-raml-or-swagger-better-for-building-apis
https://anypoint.mulesoft.com/
https://swagger.io/
https://www.openapis.org/participate/how-to-contribute/governance
https://www.openapis.org/participate/how-to-contribute/governance
https://www.w3.org/%20Submission/wadl/
https://www.w3.org/%20Submission/wadl/
https://github.com/lord/slate
https://apiblueprint.org/
https://github.com/malakhovks/ds-rest-api
https://github.com/malakhovks/ds-rest-api
Моделі і засоби систем баз даних та знань
68
About the authors:
Kyrylo Malakhov,
Junior Research Fellow.
38 Ukrainian publications,
3 International publications,
H-index: Google Scholar – 4.
http://orcid.org/0000-0003-3223-9844.
Aleksandr Kurgaev,
Doctor of Technical Science,
Professor, Leading Researcher of Department
205 at Glushkov Institute of Cybernetics.
Author of more than 240 scientific works,
including 8 monographs,
100 Patents and Author’s Certificates
for innovations and useful models.
H-index: Google Scholar – 5, Scopus – 2.
http://orcid.org/0000-0001-5348-2734.
Vitalii Velychko,
PhD, assistant professor, Senior researcher.
73 Ukrainian publications,
25 International publications,
H-index: Google Scholar – 7, Scopus – 1.
http://orcid.org/0000-0002-7155-9202.
Affilation:
V.M. Glushkov Institute of cybernetics of
National Academy of Sciences of Ukraine,
40 Glushkov ave., Kyiv,
Ukraine, 03187.
Phone: (+38) (044) 526 3348.
Email: aduisukr@gmail.com
http://orcid.org/0000-0003-3223-9844
http://orcid.org/0000-0002-7155-9202
|