REST API Development with Node.js Manage and Understand the Full Capabilities of Successful REST Development — Second Edition — Fernando Doglio REST API Development with Node.js Manage and Understand the Full Capabilities of Successful REST Development Second Edition Fernando Doglio REST API Development with Node.js Fernando Doglio La Paz, Canelones, Uruguay ISBN-13 (pbk): 978-1-4842-3714-4 ISBN-13 (electronic): 978-1-4842-3715-1 https://doi.org/10.1007/978-1-4842-3715-1 Library of Congress Control Number: 2018950838 Copyright © 2018 by Fernando Doglio 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. Managing Director, Apress Media LLC: Welmoed Spahr Acquisitions Editor: Louise Corrigan Development Editor: James Markham Coordinating Editor: Nancy Chen Cover designed by eStudioCalamar Cover image designed by Freepik (www.freepik.com) Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@springer- sbm.com, or visit www.springeronline.com. 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 e-mail [email protected], or visit http://www.apress.com/ rights-permissions. Apress titles 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 Print and eBook Bulk Sales web page at http://www.apress.com/bulk-sales. Any source code or other supplementary material referenced by the author in this book is available to readers on GitHub via the book’s product page, located at www.apress.com/9781484237144. For more detailed information, please visit http://www.apress.com/source-code. Printed on acid-free paper To my loving wife, without whom this book would’ve never happened and to my beautiful boys, without whom this book would’ve happened a lot sooner… Thank you! Table of Contents About the Author �����������������������������������������������������������������������������������������������������xi About the Technical Reviewer �������������������������������������������������������������������������������xiii Acknowledgments ���������������������������������������������������������������������������������������������������xv Introduction �����������������������������������������������������������������������������������������������������������xvii Chapter 1: REST 101 �������������������������������������������������������������������������������������������������1 Where Did It All Start? �������������������������������������������������������������������������������������������������������������������2 REST Constraints ��������������������������������������������������������������������������������������������������������������������������4 Client–Server ���������������������������������������������������������������������������������������������������������������������������4 Stateless ����������������������������������������������������������������������������������������������������������������������������������5 Cacheable ��������������������������������������������������������������������������������������������������������������������������������6 Uniform Interface ���������������������������������������������������������������������������������������������������������������������7 Layered System �����������������������������������������������������������������������������������������������������������������������9 Code-on-Demand ������������������������������������������������������������������������������������������������������������������10 Resources, Resources, Resources ����������������������������������������������������������������������������������������������11 Representations ��������������������������������������������������������������������������������������������������������������������11 Resource Identifier ����������������������������������������������������������������������������������������������������������������14 Actions �����������������������������������������������������������������������������������������������������������������������������������15 Hypermedia in the Response and Main Entry Point ��������������������������������������������������������������20 Status Codes �������������������������������������������������������������������������������������������������������������������������������26 REST vs� the Past ������������������������������������������������������������������������������������������������������������������������28 Summary�������������������������������������������������������������������������������������������������������������������������������������37 v Table of ConTenTs Chapter 2: API Design Best Practices ���������������������������������������������������������������������39 What Defines a Good API? �����������������������������������������������������������������������������������������������������������39 Developer-Friendly ����������������������������������������������������������������������������������������������������������������������40 Communication’s Protocol �����������������������������������������������������������������������������������������������������40 Easy-to-Remember Access Points ����������������������������������������������������������������������������������������41 Uniform Interface �������������������������������������������������������������������������������������������������������������������42 Extensibility ���������������������������������������������������������������������������������������������������������������������������������46 How Is Extensibility Managed? ����������������������������������������������������������������������������������������������46 Up-to-Date Documentation ���������������������������������������������������������������������������������������������������������50 Proper Error Handling �����������������������������������������������������������������������������������������������������������������53 Phase 1: Development of the Client ���������������������������������������������������������������������������������������53 Phase 2: The Client Is Implemented and Being Used by End Users ���������������������������������������55 Multiple SDK/Libraries ����������������������������������������������������������������������������������������������������������������56 Security ���������������������������������������������������������������������������������������������������������������������������������������57 Accessing the System �����������������������������������������������������������������������������������������������������������58 Scalability �����������������������������������������������������������������������������������������������������������������������������������66 Summary�������������������������������������������������������������������������������������������������������������������������������������70 Chapter 3: Node�js and REST ����������������������������������������������������������������������������������71 Asynchronous Programming �������������������������������������������������������������������������������������������������������72 Async Advanced ��������������������������������������������������������������������������������������������������������������������76 Asynchronous I/O ������������������������������������������������������������������������������������������������������������������������81 Async I/O vs� Sync I/O ������������������������������������������������������������������������������������������������������������85 Simplicity ������������������������������������������������������������������������������������������������������������������������������������87 Dynamic Typing ���������������������������������������������������������������������������������������������������������������������88 Object-Oriented Programming Simplified������������������������������������������������������������������������������89 The new Class construct from ES6����������������������������������������������������������������������������������������91 Functional Programming Support ������������������������������������������������������������������������������������������93 Duck Typing ���������������������������������������������������������������������������������������������������������������������������94 Native Support for JSON ��������������������������������������������������������������������������������������������������������95 vi Table of ConTenTs npm: The Node Package Manager ����������������������������������������������������������������������������������������������96 Who’s Using Node�js? ������������������������������������������������������������������������������������������������������������������98 Summary�������������������������������������������������������������������������������������������������������������������������������������99 Chapter 4: Architecting a REST API ����������������������������������������������������������������������101 The Request Handler, the Pre-Process Chain, and the Routes Handler ������������������������������������102 MVC: a�k�a� Model–View–Controller ������������������������������������������������������������������������������������������107 Alternatives to MVC �������������������������������������������������������������������������������������������������������������112 Response Handler ���������������������������������������������������������������������������������������������������������������������116 Summary�����������������������������������������������������������������������������������������������������������������������������������119 Chapter 5: Working with Modules ������������������������������������������������������������������������121 Our Alternatives ������������������������������������������������������������������������������������������������������������������������122 Request/Response Handling �����������������������������������������������������������������������������������������������122 Routes Handling ������������������������������������������������������������������������������������������������������������������122 Middleware ��������������������������������������������������������������������������������������������������������������������������123 Up-to-Date Documentation ��������������������������������������������������������������������������������������������������125 Hypermedia on the Response ����������������������������������������������������������������������������������������������125 Response and Request Validation ���������������������������������������������������������������������������������������125 The List of Modules �������������������������������������������������������������������������������������������������������������125 Summary�����������������������������������������������������������������������������������������������������������������������������������172 Chapter 6: Planning Your REST API ����������������������������������������������������������������������173 The Problem ������������������������������������������������������������������������������������������������������������������������������173 The Specifications ���������������������������������������������������������������������������������������������������������������177 Choosing the Right Modules for the Job �����������������������������������������������������������������������������188 Summary�����������������������������������������������������������������������������������������������������������������������������������189 Chapter 7: Developing Your REST API �������������������������������������������������������������������191 Minor Changes to the Plan ��������������������������������������������������������������������������������������������������������192 Simplification of the Store–Employee Relationship�������������������������������������������������������������192 Adding Swagger UI ��������������������������������������������������������������������������������������������������������������192 Simplified Security ��������������������������������������������������������������������������������������������������������������193 vii Table of ConTenTs A Small Backdoor for Swagger ��������������������������������������������������������������������������������������������193 MVC �������������������������������������������������������������������������������������������������������������������������������������194 Folder Structure ������������������������������������������������������������������������������������������������������������������������194 The Source Code �����������������������������������������������������������������������������������������������������������������������196 config �����������������������������������������������������������������������������������������������������������������������������������197 Controllers ���������������������������������������������������������������������������������������������������������������������������197 lib �����������������������������������������������������������������������������������������������������������������������������������������228 Models ���������������������������������������������������������������������������������������������������������������������������������237 request_schemas ����������������������������������������������������������������������������������������������������������������243 schemas ������������������������������������������������������������������������������������������������������������������������������245 swagger-ui���������������������������������������������������������������������������������������������������������������������������254 Root Folder ��������������������������������������������������������������������������������������������������������������������������255 Summary�����������������������������������������������������������������������������������������������������������������������������������259 Chapter 8: Testing your API ����������������������������������������������������������������������������������261 Testing 101��������������������������������������������������������������������������������������������������������������������������������261 The Definition ����������������������������������������������������������������������������������������������������������������������261 The Tools ������������������������������������������������������������������������������������������������������������������������������264 Best Practices ����������������������������������������������������������������������������������������������������������������������271 Testing with Node�js ������������������������������������������������������������������������������������������������������������������272 Testing Without Modules �����������������������������������������������������������������������������������������������������272 Mocha ����������������������������������������������������������������������������������������������������������������������������������275 Summary�����������������������������������������������������������������������������������������������������������������������������������282 Chapter 9: Deploying into Production �������������������������������������������������������������������283 Different Environments �������������������������������������������������������������������������������������������������������������283 The Classical Development Workflow����������������������������������������������������������������������������������283 Tips for Your Production Environment ���������������������������������������������������������������������������������286 viii Table of ConTenTs Doing the Actual Deployment ����������������������������������������������������������������������������������������������������291 Shipit �����������������������������������������������������������������������������������������������������������������������������������292 What about Continuous Integration? �����������������������������������������������������������������������������������295 PM2 �������������������������������������������������������������������������������������������������������������������������������������296 Summary�����������������������������������������������������������������������������������������������������������������������������������302 Chapter 10: Troubleshooting ���������������������������������������������������������������������������������303 Asynchronous Programming �����������������������������������������������������������������������������������������������������303 The Controllers Action’s Code ����������������������������������������������������������������������������������������������304 The Middleware Functions ��������������������������������������������������������������������������������������������������306 Issues Configuring the Swagger UI �������������������������������������������������������������������������������������������308 CORS: a�k�a� Cross-Origin Resource Sharing ����������������������������������������������������������������������������310 Summary�����������������������������������������������������������������������������������������������������������������������������������314 Index ���������������������������������������������������������������������������������������������������������������������315 ix About the Author Fernando Doglio has worked as a developer for the past 13 years. In that time, he has come to love the Web and has had the opportunity to work with most leading technologies, such as PHP, Ruby on Rails, MySQL, Node.js, Angular.js, AJAX, REST APIs, and others. For the past 4 years Fernando has also been working as a Technical Manager and Technical Lead for BigData projects. In his spare time, Fernando likes to tinker, learn new things, and write technical articles and books such as this one. He’s also a big open source supporter, always trying to bring new people into that realm. When not programming, he is spending time with his family. Fernando can be contacted on Twitter @deleteman123 or online at www.fernandodoglio.com. xi