Download (601Kb)
Total Page:16
File Type:pdf, Size:1020Kb
ePubWU Institutional Repository Stefan Sobernig and Michael Maurer and Mark Strembeck RAMLFlask: Managing artifact coupling for Web APIs Paper Original Citation: Sobernig, Stefan and Maurer, Michael and Strembeck, Mark (2019) RAMLFlask: Managing artifact coupling for Web APIs. This version is available at: https://epub.wu.ac.at/7367/ Available in ePubWU: December 2019 License: Creative Commons Attribution 3.0 Austria (CC BY 3.0 AT) ePubWU, the institutional repository of the WU Vienna University of Economics and Business, is provided by the University Library and the IT-Services. The aim is to enable open access to the scholarly output of the WU. http://epub.wu.ac.at/ RAMLFlask Managing artifact coupling for Web APIs Stefan Sobernig Michael Maurer Mark Strembeck WU Vienna Independent Developer WU Vienna Vienna, Austria [email protected] Vienna, Austria [email protected] [email protected] ABSTRACT 2 @app.route('/status/<order_id>', methods=['GET', 'POST']) 3 def order_status(order_id): Modern Web applications rely more and more on communication 4 if request.method == 'POST': with Web services for providing their composite functionality. Cur- 5 # Retrieves the status of a specific order 6 set_order_status(order_id, request.form['statusCode']) rently, one of the most popular method of providing Web services is 7 return via HTTP-based APIs—a.k.a. Web APIs with or without Representa- 8 else: tional State Transfer. Such services will usually be implemented in 9 # Sets the status of a specific order 10 return Response(get_order_status(order_id), some general purpose language (e.g., Python) and involve several 11 mimetype='application/json') stakeholders for development and for maintenance (e.g., developers, testers, architects). Enabling effective communication and devel- opment between all of these stakeholders can be difficult though. Listing 1: An exemplary Web service order_status im- Software languages specific to describing service interfaces allow plemented using Flask exposed via an HTTP-based API: for providing a further level of abstraction, which can improve @app.route(). In Flask, @app.route signals the use of a func- communication between stakeholders while also making develop- tion decorator to define a route and to bind it to a handler ment under evolution less prone to error. This paper documents a function. systematic approach (RAMLFlask) to extending Web application frameworks (Flask) to include support for interface-description languages (IDLs such as RAML) and code generation. The contribu- tions include a systematic elicitation to requirements on interface of a code document. The Python example in Listing 1 showcases descriptions and needs for managing coupled development artifacts a minimal Web service implementation for managing order status from the perspective of developers of Web services and composite using Flask. As an example of boilerplate, there is annotation code Web applications. This is based on an overview of relevant litera- (on line 4) for each and every route to enable request handling by ture, complemented by expert interviews with professional Web the responsible application code (e.g., some getter and setter func- developers. tions) based on the HTTP method used (GET, POST). In addition, the interface details (HTTP methods, parameter representation, KEYWORDS content type) appear scattered over the application code (see, e.g., Web engineering, Web application integration, artifact coupling, lines 7 and 10). Boilerplate code and code scattering are tedious to interface description, application generator, Flask, RAML handle manually, especially for larger Web APIs. Publicly accessible Web APIs contain up to 200+ operations (routes), with a mid-range 1 INTRODUCTION of APIs having 7–50 operations [12]. The Web APIs looked at in Building a Web application involves exposing server-side appli- this paper are representative of that spectrum: between 4 (Flickr) cation functionality as services accessible via Web APIs, to be to 223 routes (GitHub; see Section 5.1). incorporated by client-side building blocks. A Web application- Also, Web APIs and their implementations are subjected to programming interface (Web API) defines the contract between change running in parallel with changes in application code. For client-side and server-side blocks of a Web application in terms example, a Web API may be further developed by adding, by re- of the functionality offered and used, respectively, by means of moving, or by altering services or their details (e.g., parameters). In HTTP—i.e., resources and the HTTP virtual machine. A Web API addition, the details of mapping between the application code (i.e., can contract additional details depending on their architectural getters and setters in Listing 1) and a resource-orientated HTTP context. This context typically imposes additional architectural connector may change over time (e.g., HTTP methods used, pa- constraints on a Web service and its API. The constraints follow rameter representation). In these cases, in particular upon high from the architectural styles used, such as Representational State frequency of change and/ or for larger Web APIs, tracking changes Transfer (REST, esp. HATEOAS) or microservices. at the level of boilerplate code does incur extra maintenance effort. Web APIs and the so-provided Web services are typically imple- For this paper, we reviewed the change history of selected Web APIs mented on top of a Web application framework (e.g., Flask). To this and found that, for these projects, more than 50% of commits made end, defining and implementing a Web API often involves codethat to API definition documents during the review periods affected the is boilerplate and scattered. This boilerplate code is incurred by the boilerplate code. By affected, we mean that some (typically, manual) respective framework to implement the API on top of HTTP, which rewriting of boilerplate code (route definitions) had entered a given requires highly similar code sections to be included at many places commit (see Section 5.2). 2 /status: used, this makes an interface description the single source of truth 3 /{order_id}: for all involved stakeholder roles. 4 get: 5 description: Retrieve the status of a specific order On the downside, an interface-description document for a Web 6 responses: API introduces the complexity of managing co-changes [11] be- 7 200: tween documents. Changes to the interface descriptions must be- 8 body: 9 application/json: come tracked by the code documents (e.g., by triggering re-generation 10 post: of the latter) and vice versa. At the same time, modifications to the 11 description: Sets the status of a specific order 12 body: application code should not interfere with API-related changes 13 multipart/form-data: in unintended ways. To this end, this paper makes the following 14 properties: contributions: 15 statusCode: 16 description: The status identifier to be stored • A critical-analytical comparison of established generative 17 required: true techniques for their fit to manage artifact coupling (incl. 18 responses: 19 200: propagating changes) in an automated manner between an interface description (RAML) and the generated Web API (Flask) code (see Section 4.1). Listing 2: An interface description using RAML correspond- • A proof-of-concept implementation of a mixed generative ing to the Web API defined in Listing 1 technique (generation gap and delegation) for RAML doc- uments and Flask-based Web API implementations (see Sec- tion 4.2). • A twofold validation of the proof-of-concept implementation On top of that, Web APIs have multiple technical and non- is performed. Second, the generator implementation is tested technical stakeholder roles during development of a Web applica- for its space and time performance on real-world Web APIs tion. Examples include developers responsible for different server- (see Section 5.1). Second, the chosen technique is tested for side building blocks (incl. or excl. the Web API itself), developers its coverage of typical changes to Web APIs (see Section 5.2). for client-side building blocks, developers writing tests against the The proof-of-concept implementation plus test suite, as well as Web API, documentation writers documenting the Web API, opera- a reproduction package incl. the collected interface descriptions is tors overseeing deployed Web applications and their API endpoints; available from a supplemental Web site.1 as well as management roles to the extent the Web API must be aligned with important details of a business model (e.g., usage poli- 2 WEB APIS cies, service levels, pricing). Development involves communication and close, document-based interactions between these stakeholder roles. When the Web API is only defined in terms of its imple- Identifier Platform Service Service mentation in code, this raises barriers to communication and to model model provide Service interaction, esp. for non-technical roles being limited to code docu- maps to ments targeting a single Web-application platform (i.e., a specific Interface represents Service programming language, framework, and application server). But Resource Interface require Service also, technical roles may suffer from a code-only definition ofaWeb model model generated from Client API, due to the API and application code being interleaved; or API interface-description e.g., resource-oriented, HTTP-based code being scattered over multiple development documents (config- languages: OAS, (RESTful) application