From OpenAPI Fragments to API Pattern Primitives and Design Smells

In the past few years, the OpenAPI Specification (OAS) has emerged
as a standard description language for accurately modeling Web
APIs. Today, thousands of OpenAPI descriptions can be found by
mining open source repositories. In this paper, we attempt to exploit
these artifacts to extract commonly occurring building blocks used
inWeb API structures, in order to assistWeb API designers in their
modelling task. Our work is based on a fragmentation mechanism,
that starts from OpenAPI descriptions ofWeb APIs to extract their
structures, then fragment these structures into smaller blocks. This
approach enabled us to extract a large dataset of reoccurring fragments
from a collection of 6619 API specifications. Such fragments
have been found multiple times in the same or across different APIs.
We have classified the most reoccurring fragments into four pattern
primitives used to expose in the API access to collections of items.
We distinguish for each primitive variants from design smells. This
classification is based on the specific combinations of operations
associated with the collection items and on an in-depth analysis of
their natural language labels and descriptions. The resulting pattern
primitives are intended to support designers who would like to introduce
one or more collections for a specific class of items in their
HTTP-based API.