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 in Web API structures, in order to assist Web API designers in their modelling task. Our work is based on a fragmentation mechanism, that starts from OpenAPI descriptions of Web 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.