© 2015. All Rights Reserved. Undisturbed REST First-look Edition May 2015, PDF ISBN 978-1-329-11656-6 To learn more, visit us online at http://www.mulesoft.com/restbook Published by MuleSoft, 77 Geary Street, Suite 400, San Francisco, CA 94108 A Note from the Author First and foremost, I want to thank you—the reader—for taking time out of your busy schedule to read this book. Undisturbed REST is not designed to be a tell-all book that covers every line of code in regards to building your API, but rather a book that takes you back to the basics and focuses on how to not just build an API, but build a long- lived API that your users will love. An API that is carefully created to be extendable and flexible, and will save your users time, money and energy in the long run. As this is the very first edition of this book, I would ask that if you find mistakes you are both willing to forgive them and willing to let me know so that they can be corrected. This feedback will be very much appreciated and can be directed to [email protected] with the subject “Errata.” Please also understand that while I would love to answer any questions, this may not be feasible from a time standpoint. But I would encourage you all to post freely in the MuleSoft forums (under API), and I, a member of my team or someone from our community will be glad to help out. I would also like to thank Dr. Roy Fielding for being extremely gracious in letting me include his original doctoral dissertation diagrams in this book to demonstrate how the different constraints of REST work together. I’d also like to thank Arnaud Lauret (@apihandyman) and Jason Harmon (@jharmn) for taking the time to review this book prior to publication. As well as a very big thank you to Phil Hunter who spent countless hours copy-editing, and Chris Payne (@chrisypayne) who meticulously designed the book’s amazing cover. Last but not least, I want to thank MuleSoft for giving me time to write this book, and for making it freely available. I have always believed in the power of community, and been thankful for all of the valuable lessons I have learned from it over the years. I want to also thank my many mentors, my family, and my friends for their patience, love, and support. Please enjoy this version of Undisturbed REST, a Guide to Designing the Perfect API—a book that is dedicated both to you and the amazing developer community as a whole. – Mike Stowe (@mikegstowe) Table of Contents 1. What is an API 1 Web APIs 3 REST 6 2. Planning Your API 15 Questions to Ask 16 3. Designing the Spec 25 Versioning 26 Spec-Driven Development 30 Choosing a Spec 35 4. Using RAML 39 Query Parameters 43 Responses 44 ResourceTypes and Traits 45 5. Prototyping and Agile Testing 49 Getting Developers Involved 53 Getting Feedback 56 6. Authorization and Authentication 59 Generating tokens 62 OAuth2 64 OAuth and Security 68 Adding OAuth to RAML 71 7. Designing Your Resources 73 Nouns 74 Content-types 76 Versioning 83 Caching 88 8. Designing Your Methods 91 Items vs Collections 92 HTTP Methods 93 9. Handling Responses 101 HTTP Status Codes 102 Errors 105 10. Adding Hypermedia 117 HATEOAS 121 Hypermedia Specs 124 Hypermedia Challenges 136 11. Managing with a Proxy 139 API Access 140 Throttling 142 SLA Tiers 144 Security 147 12. Documenting and Sharing Your API 153 API Console 166 API Notebook 170 Support Communities 173 SDKs and Client Libraries 174 13. A Final Thought 179 Appendix: More API Resources 183 Appendix: Is Your API Ready? 187 1 What is an API? In the simplest of terms, API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. In fact, each time you check the weather on your phone, use the Facebook app or send an instant message, you are using an API. Every time you use one of these applications, the application on your phone is connecting to the Internet and sending data to a server. The server then retrieves that data, interprets it, performs the necessary actions and sends it back to your phone. The application then interprets that data and presents you with the information you wanted in a human, readable format. What an API really does, however, is provide a layer of security. Because you are making succinct and explicit calls, your phone’s data is never fully exposed to the server, and likewise the server is never fully exposed to your phone. Instead, each communicates with small packets of data, sharing only that which is necessary—kind of like you ordering food from a drive- 1 2 through window. You tell the server what you would like to eat, they tell you what they need in return and then, in the end, you get your meal. Many Types of APIs There are many types of APIs. For example, you may have heard of Java APIs, or interfaces within classes that let objects talk to each other in the Java programming language. Along with program-centric APIs, there are also Web APIs such as the Simple Object Access Protocol (SOAP), Remote Procedure Call (RPC), and perhaps the most popular—at least in name— Representational State Transfer (REST). While the function of an API may be fairly straightforward and simple, the process of choosing which type to build, understanding why that type of API is best for your application, and then designing it to work effectively has proven to be far more difficult. One of the greatest challenges of building an API is building one that will last. This is especially true for Web APIs, where you are creating both a contract between you and your users and a programming contract between your server and the client. In this book, we’ll take a look at some of the different types of APIs, but then we’ll switch gears and focus on building a REST API as defined by Dr. Roy Fielding. We’ll cover important principles that are often ignored—and while some of these may seem a little painful or like they just create more work, you’ll find that by adhering to these best practices you will not only create a better API, but save a lot of time and money doing so. So without further ado, let’s get started. 2 Web APIs A Web API, otherwise known as a Web Service, provides an interface for Web applications, or applications that need to connect to each other via the Internet to communicate. To date, there are over 13,000 public APIs that can be used to do everything from checking traffic and weather, to updating your social media status and sending Tweets, to even making payments. In addition to the 13,000 public APIs, there are hundreds of thousands more private Web APIs, or APIs that are not available for consumption by the general public, that are used by companies to extend their capabilities and services across a broad scope of use-cases, including multiple devices. One of the most common forms of a private cross-device Web APIs would be an API written for a mobile application that lets the company transmit data to the app on your phone. Since 2005, the use of Web APIs has exploded exponentially, and multiple Web formats and standards have been created as technology has advanced: 3 4 Early on, one of the most popular enterprise formats for APIs was SOAP. With the emergence of JavaScript Object Notation (JSON), we saw more reliance on HTTP and the growth of JSON-RPC APIs, while REST has grown in popularity and quickly become the de facto standard for general Web APIs today. SOAP SOAP was designed back in 1998 by Dave Winer, Don Box, Bob Atkinson and Mohsen Al-Ghosein for Microsoft Corporation. It was designed to offer a new protocol and messaging framework for the communication of applications over the Web. While SOAP can be used across different protocols, it requires a SOAP client to build and receive the different requests, and relies heavily on the Web Service Definition Language (WSDL) and XML: <?xml  version="1.0"?>   <soap:Envelope   xmlns:soap="http://www.w3.org/2001/12/soap-­‐envelope"   soap:encodingStyle="http://www.w3.org/2001/12/soap-­‐ encoding">     <soap:Body  xmlns:m="http://www.example.com/weather">      <m:GetWeather>          <m:ZipCode>94108</m:ZipCode>      </m:GetWeather>   </soap:Body>     </soap:Envelope>   Early on, SOAP did not have the strongest support in all languages, and it often became a tedious task for developers to integrate SOAP using the Web Service Definition Language. However, SOAP calls can retain state, something that REST is not designed to do. 4