Best Practices for the Design of Restful Web Services
Total Page:16
File Type:pdf, Size:1020Kb
See discussions, stats, and author profiles for this publication at: https://www.researchgate.net/publication/301694429 Best Practices for the Design of RESTful Web Services Article in Proceedings - International Conference on Software Engineering · November 2015 CITATION READS 1 162 5 authors, including: Pascal Giessler Michael Gebhart Karlsruhe Institute of Technology iteratec GmbH 4 PUBLICATIONS 1 CITATION 34 PUBLICATIONS 126 CITATIONS SEE PROFILE SEE PROFILE Roland Steinegger Karlsruhe Institute of Technology 7 PUBLICATIONS 2 CITATIONS SEE PROFILE Some of the authors of this publication are also working on these related projects: Microservice Architecture Security View project Best Practices for the Design of RESTful Web Services View project All content following this page was uploaded by Roland Steinegger on 29 April 2016. The user has requested enhancement of the downloaded file. ICSEA 2015 : The Tenth International Conference on Software Engineering Advances Best Practices for the Design of RESTful Web Services Pascal Giessler Dmitrij Sarancin, Roland Steinegger, and Michael Gebhart and Sebastian Abeck iteratec GmbH Cooperation & Management Stuttgart, Germany Karlsruhe Institute of Technology (KIT) Email: [email protected], Karlsruhe, Germany Email: [email protected] Email: [email protected], Email: [email protected], Email: [email protected] Abstract—The trend towards creating web services based on the be easily applied during the development of RESTful web ser- REpresentational State Transfer (REST) is unbroken. Because of vices , as well as for analyzing existing RESTful web services. this, several best practices for designing RESTful web services More precisely, we have defined eight different categories and have been created in research and practice to ensure a certain found an amount of 23 best practices that will be described level of quality. But, these best practices are often described in this paper. These best practices provide guidelines for the differently with the same meaning due to the nature of natural design of RESTful web services to support certain quality language. In addition, they are not collected and presented in a central place but rather distributed across several pages in goals such as the usability of the Web API. Furthermore, their the World Wide Web, which impedes their application even usage also results in an increasing consistency of web services. further. In this article, we identify, collect, and categorize several For illustration, we have used this set of best practices best practices for designing RESTful web services and illustrate for the development of the CompetenceService as part of their application on a real system to show their application. the SmartCampus system at the KIT. The SmartCampus is For illustration purpose, we apply the best practices on the CompetenceService, an assistance service of the SmartCampus a system which provides functionality for students, guests and system developed at the Karlsruhe Institute of Technology (KIT). members of an university to support their daily life. Today, the SmartCampus already offers some services, such as the Keywords–REST; RESTful; best practices; collection; catalog; ParticipationService to support the decision-making process design; quality; research and practice between students, professors and members of the KIT with a new approach called system-consenting [4]. The developed services at the SmartCampus are based on REST, so that I. INTRODUCTION they can be used for several different devices as a lightweight Over the years, more and more web services based on the alternative to SOAP. architectural style REST were developed, which uses existing The current paper is structured as follows: In Section II, functionality from the application layer protocol Hypertext the architectural style REST will be described in detail to lay Transfer Protocol (HTTP) [1] [2]. This results in an increasing the foundation for this paper. Afterwards, existing papers and interest compared to traditional web services with Simple articles will be discussed in Section III to show the necessity Object Access Protocol (SOAP), which can be shown in a of identification, collection, and categorization of existing best Google Trend Analysis with the keywords REST and SOAP practices for RESTful web services. The CompetenceService or in the increasing usage of REST- instead of SOAP-based is used to illustrate the best practices will be presented in web services [1]. Also big companies, such as Twitter or Section IV. In Section V, the best practices for RESTful web Amazon, are using REST-like interfaces for their services, services will be presented in detail so that they can be easily which are shown in their Application Programming Interface applied during the design phase of such web services. Finally, (API) documentations. a summary of this paper and an outlook on further work will Despite this trend, there are still no standards or guidelines be given in Section VI. about how to develop a RESTful web service. Instead of this, several best practices in research and practice have been developed and were published in a range of articles, magazines II. FOUNDATION and pages in the World Wide Web (WWW). But, these REST is an architectural style, which was developed and best practices were often described differently with the same first introduced by Fielding [5] in his dissertation. According semantics due to the nature of natural language [3]. This results to Garlan and Shaw [6], an architectural style can be described in several obscurities and misconceptions by applying these as follows: “an architectural style determines the vocabulary best practices. of components and connectors that can be used in instances of To overcome these issues, we have collected, categorized that style, together with a set of constraints on how they can and formalized several best practices in a way that they can be combined.” [6, p. 6]. Copyright (c) IARIA, 2015. ISBN: 978-1-61208-438-1 392 ICSEA 2015 : The Tenth International Conference on Software Engineering Advances For the design of REST, Fielding [5] has identified four As The Engine Of Application State (HATEOAS), which is not key characteristics, which were important for the success taken into account by all of the prior articles. But, the focus of of the current WWW [7]. To ensure these characteristics, this work is the comprehensive understanding of REST rather the following constraints were derived from existing network than providing best practices for a concrete implementation to architectural styles together with another constraint for the reduce the complexity of development decisions. uniform interface [5]: 1) Client and Server, 2) Statelessness, In Burke [13], Burke presents a technical guide of how to 3) Layered Architecture, 4) Caching, 5) Code on Demand and develop web services based on the Java API for RESTful Web 6) Uniform Interface. The latter one represents the Web API Services (JAX-RS) specification. But, this work focuses on the of RESTful web services and can be seen as an umbrella implementation phase rather than the design phase of a web term, since it can be decomposed into four sub-constraints [7]: service, where the necessary development decisions have to be 6.1) Identification of resources, 6.2) Manipulation of resources made. through representations, 6.3) Self-descriptive messages and 6.4) Hypermedia. IV. SCENARIO If all of these constraints are fulfilled by a web service, The SmartCampus is a modern web application, which it can be called RESTful. The only exception is “Code on simplifies the daily life of students, guests, and members at the Demand”, since it is an optional constraint and has not to be university. Today, it offers several services, such as the Partic- implemented by a web service. ipationService for decision-making [4], the SmartMeetings for discussions or the CampusGuide for navigation and orientation III. STATE OF THE ART on the campus. By using non-client specific technologies, the This section discusses different articles, magazines and services can be offered to a wide range of different client approaches in the context of RESTful best practices, which platforms, such as Android or iOS. respect the architectural style REST and its underlying con- cepts. The CompetenceService is a new service as part of the SmartCampus to capture and semantically search competences In Fielding [5], Fielding presents the structured approach in the area of information technology. For easier acquisition for designing the architectural style REST, while it remains of knowledge information, the CompetenceService offers the unclear how a REST-based web service can be developed in a import of competence and profile information from various systematic and comprehensible manner. Furthermore, there is social networks such as LinkedIn or Facebook. The resulting also a lack of concrete examples of how hypermedia can be knowledge will be represented by an ontology, while the profile used as the engine of the application state, which can be one information will be saved in a relational database. SPARQL reason why REST is understood and implemented differently. Protocol And RDF Query Language (SPARQL) is used as Mulloy [8] presents different design principles and best the query language for capturing and searching knowledge practices for Web APIs, while he puts the focus on “pragmatic information in the ontology. REST”. By “pragmatic REST” the author means