Creating Maintainable APIs

Transcription

1 Creating Maintainable APIs A Practical, Case-Study Approach Ervin Varga

2 Creating Maintainable APIs: A Practical, Case-Study Approach Ervin Varga Expro I.T. Consulting, Kikinda Serbia ISBN-13 (pbk): ISBN-13 (electronic): DOI / Library of Congress Control Number: Copyright 2016 by Ervin Varga This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights. While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein. Cover image designed by Freepik Managing Director: Welmoed Spahr Lead Editor: Steve Anglin Technical Reviewer: Jaroslav Tulach and Sverrir Sigmundarson Editorial Board: Steve Anglin, Pramila Balan, Laura Berendson, Aaron Black, Louise Corrigan, Jonathan Gennick, Robert Hutchinson, Celestin Suresh John, Nikhil Karkal, James Markham, Susan McDermott, Matthew Moodie, Natalie Pao, Gwenan Spearing Coordinating Editor: Mark Powers Copy Editor: Teresa F. Horton Compositor: SPi Global Indexer: SPi Global Artist: SPi Global Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY Phone SPRINGER, fax (201) , orders-ny@springer-sbm.com, or visit Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation. For information on translations, please rights@apress.com, or visit Apress and friends of ED books may be purchased in bulk for academic, corporate, or promotional use. ebook versions and licenses are also available for most titles. For more information, reference our Special Bulk Sales ebook Licensing web page at Any source code or other supplementary materials referenced by the author in this text are available to readers at For detailed information about how to locate your book s source code, go to Readers can also access source code at SpringerLink in the Supplementary Material section for each chapter. Printed on acid-free paper

3 To my family (my wife Zorica with my sons Andrej and Stefan), who put in the lion's share of the effort to make this book a reality. I'm grateful to them!

4 Contents at a Glance About the Author... xiii About the Technical Reviewers...xv Acknowledgments....xvii Introduction...xix Chapter 1: Information Hiding and APIs... 1 Chapter 2: Modular Design Chapter 3: Designing Classes for Reuse Chapter 4: TDD as an API Design Technique Chapter 5: Identifying Resources Chapter 6: Versioning REST APIs Chapter 7: Encoding Actions on Resources Chapter 8: Implementing Synchronous and Asynchronous REST APIs Chapter 9: Documenting REST APIs Chapter 10: Testing REST APIs Chapter 11: Implementing Messaging APIs Chapter 12: Apache Kafka as a Messaging Hub Chapter 13: Testing Messaging APIs Chapter 14: Schema-Based Messages v

5 CONTENTS AT A GLANCE Chapter 15: The Core JSON API Chapter 16: Evolving the JSON API Chapter 17: Katharsis Index vi

6 Contents About the Author... xiii About the Technical Reviewers...xv Acknowledgments....xvii Introduction...xix Chapter 1: Information Hiding and APIs... 1 Entropy and Its Impact on Assumptions... 4 Case Study: API for Calculating an Integral of a Function... 8 Version I: Direct Summation (Riemann Sum)... 8 Version II: Simpson s Rule... 9 Version III: Romberg s Method Summary...14 References...16 Chapter 2: Modular Design API-Driven Development Use Case Abstraction Data Encapsulation Type Coercion Case Study Standard Java s Limitations OSGi as a Disruptive Technology vii

7 CONTENTS OSGi in Action...29 Modular Integral Calculation Summary...40 References...43 Chapter 3: Designing Classes for Reuse Case Study: Client of Reuse Version I Version II Version III Conclusion Case Study: Provider of Reuse Summary...65 References...67 Chapter 4: TDD as an API Design Technique Case Study: TDD Doesn t Replace OOD Principles Conclusion Case Study: Tests Are Rubbish Without TDD Case Study: Retrofitting Tests to Follow TDD Case Study: Introduction to BDD Case Study: TDD for APIs Is a Complex Topic The Subtleties of the Spliterator API Checking for API Incompatibilities Between Different Versions Postprocessor as a Rescue for Bugs Better Serialization Support Performance Guarantees Are Mandatory The Reworked Version Ready for Publication Summary...93 References...95 viii

8 CONTENTS Chapter 5: Identifying Resources Case Study: Problem Reports Microservice Discovering and Describing Resources Summary References Chapter 6: Versioning REST APIs The Main Traits of REST API Versioning Altering the Resource URLs API Keys as a Way to Control Versioning The Importance of Stable UR[IL]s Switching API Versions Upgrading the HTTP Version Summary Reference Chapter 7: Encoding Actions on Resources Implementing the Core Features Interaction of Resources via Hypermedia Controls Skeleton of the Service The Remaining Representations and Controllers Smoke Testing the Service Adding an Ontology Summary References Chapter 8: Implementing Synchronous and Asynchronous REST APIs Client-Controlled Asynchrony Server-Controlled Asynchrony Case Study: Favorite Problem Report Summary Reference ix

9 CONTENTS Chapter 9: Documenting REST APIs Case Study: Attempting the Universal Method Case Study: Producing a Swagger API Specification Extending the Service to Implement This New Specification Smoke Testing the Service Generating the Dynamic HTML Client Summary Reference Chapter 10: Testing REST APIs Case Study: Testing with a Level 2 Tool Examine the Service Use Case Find General Information Use Case Delete a Problem Report Use Case Load Testing the Examine the Service Use Case Case Study: Testing with a Level 3 Tool Summary Reference Chapter 11: Implementing Messaging APIs Case Study: Load Profile Generator Message Design Project Setup RPC Protocol Design Service Implementation Integration Test Summary References x

10 CONTENTS Chapter 12: Apache Kafka as a Messaging Hub Case Study: Distributed LP Classification System Setting Up Kafka Refactoring the Smart Meter to Use Kafka Implementing the LP Classifier Summary References Chapter 13: Testing Messaging APIs Case Study: Attaining Automated Integration Tests Refactoring the ClientServerTest Test Case Testing the LP Classifier Full End-to-End Test Summary Reference Chapter 14: Schema-Based Messages Version 1.0.0: Simple Lottery Ticket Version 1.0.1: Bug Fix Version 1.1.0: Going International Version 1.2.0: Automaton-Pick Feature Version 2.0.0: Multigame Lottery Ticket Version 2.1.0: Separate Game Start Times Summary References Chapter 15: The Core JSON API Case Study of an Industry Standard Message Format Common Information Model of a Power System Serialization of a Power Network with CIM/XML xi

11 CONTENTS Practical Guide to JSON API Fetching an Individual Resource Fetching Related Resources with Autoinclusion Fetching Relationships Fetching a Collection of Resources Fetching Related Resources with Explicit Inclusion Fetching a Partial View of an Individual Resource Creating a New Resource Updating a Resource Deleting a Resource Summary References Chapter 16: Evolving the JSON API A Case Study of Integrating Disparate Data Sources Main Directions to Evolve the JSON API Extensions Profiles Summary References Chapter 17: Katharsis Community Game Service The Architecture of the Community Game Service Specifying Resources Specifying Resource and Relationship Repositories A Sample Session with the Community Game Service Summary Reference Index xii

12 About the Author Ervin Varga has been in the software industry as a professional software engineer since As an owner of the software consulting company Expro I.T. Consulting ( ), he is always in touch with production software. He is an IEEE Software Engineering Certified Instructor, and an assistant professor at the University of Novi Sad, Faculty of Technical Sciences, Novi Sad, Serbia. He was the primary technical reviewer for the book Thinking in Java (4th ed.) written by Bruce Eckel. He was also the co-author with Bruce Eckel of the book Thinking in Java (4th ed.) Annotated Solutions Guide published by MindView LLC in Ervin actively participates in open-source projects. He is the author of the Docker image (evarga/jenkins-slave) to serve as a Jenkins slave node in distributed builds. He has an MSc in computer science and a PhD in electrical engineering. His thesis was an application of software engineering and computer science in the domain of electrical power systems. LinkedIn profile: linkedin.com/in/ervinvarga e.varga@ieee.org xiii

13 About the Technical Reviewers Jaroslav Tulach is the founder and initial architect of NetBeans, later acquired by Sun Technologies. As creator of the technology behind NetBeans, he is still with the project to find ways to improve design skills among the programmers who contribute to the success of the NetBeans open source project. Sverrir Sigmundarson has more than 15 years of industry experience building high-performance, missioncritical software for the finance and software industries. He holds an MSc degree in Computer Science from Reykjavik University in Iceland. He is currently on a special assignment as a stay-at-home-dad living in Strasbourg, France, with his wife and son. He can be contacted through his web site, coruscantconsulting. co.uk or via linkedin.com/in/sverrirs. xv

14 Acknowledgments Publishing a book is a team effort. I am really thankful to the team at Apress, especially Steve Anglin, Mark Powers, Laura Berendson, Alexander James, and Amrita Stanley for their tremendous support and professionalism. Their experience in the book publication domain was indispensable. I am also happy and indebted that Jaroslav Tulach accepted the role of the technical reviewer. His comments and mathematically precise methodological reviewing approach made huge quality improvements in the text. I would also like to thank Dr. Heinz Kabutz for recommending and introducing me to Jaroslav. Many thanks to Sverrir Sigmundarson for reviewing Chapters 10 through 13 and his useful remarks. xvii

15 Introduction The goal of this book is to teach you how to design maintainable application programming interfaces (APIs) with reuse in mind. Of course, by reuse I don t mean simply visiting and starting to search the API directory, although if you find something interesting there, then it might be a good source of inspiration. It is hard to encompass everything regarding APIs in a single book. It is even impossible to fully cover just one particular type of API (like REST) in one book. Therefore, the focus here is solely on the gist of producing evolvable APIs. Nevertheless, learning the foundations is the most important thing before crafting more complex solutions (including a business model around APIs using some of the available API platforms, like the one provided by Apigee). The book is made up of four logical parts: basic principles of API design in the realm of object-oriented design (OOD) and object-oriented programming (OOP), HTTP REST APIs, messaging APIs, and JSON API as a concrete, powerful hypermedia-driven media type. These parts can be read in any order, but I suggest you start with Part I. This presents some essential topics, which are required to understand the rest of the text. Part III is independent of Parts II and IV. I would recommend reading Part II before Part IV. Of course, the best result is achieved by following the text in a linear fashion. The book tries to balance stability and pragmatism. The main ideas are presented in a form that will hopefully remain valid for the next couple of years. On the other hand, to make the elaborations practical, I was forced to stick to concrete versions of frameworks, which will surely change much quicker than the accompanying principles and methods. On the other hand, without practical case studies, the reader will have a hard time mapping high-level concepts to everyday situations. To compensate on the side of volatility for the referenced frameworks, the book also has a Github repository belonging to Apress. This will be updated as new versions of the frameworks are published. Some novel, interesting projects, like GraphQL ( ), were not examined as they are mostly in draft form, so considerable changes are expected in their specifications in the near future. The book also tries to introduce the reader to the Semantic Web technology in a very lightweight manner. This is done in an attempt to demonstrate the semantic gap problem in current REST APIs, and how it could be mitigated by using linked data concepts. Many advanced topics, like semantic inference and reasoning, aren t scrutinized, although they are the most beautiful and powerful aspects of the Semantic Web movement. xix