api-design-ebook-2016-03.pdfVIP

Web API Design Crafting Interfaces that Developers Love Brian Mulloy Table of Contents Web API Design - Crafting Interfaces that Developers Love Introduction 3 Nouns are good; verbs are bad 4 Plural nouns and concrete names 8 Simplify associations - sweep complexity under the ‘?’ 9 Handling errors 10 Tips for versioning 13 Pagination and partial response 16 What about responses that don’t involve resources? 19 Supporting multiple formats 20 What about attribute names? 21 Tips for search 22 Consolidate API requests in one subdomain 23 Tips for handling exceptional behavior 25 Authentication 27 Making requests on your API 28 Chatty APIs 30 Complement with an SDK 31 The API Façade Pattern 32 2 Web API Design - Crafting Interfaces that Developers Love Introduction If you’re reading this, chances are that you care about designing Web APIs that developers will love and that you’re interested in applying proven design principles and best practices to your Web API. One of the sources for our design thinking is REST. Because REST is an architectural style and not a strict standard, it allows for a lot of flexibly. Because of that flexibility and freedom of structure, there is also a big appetite for design best practices. This e-book is a collection of design practices that we have developed in collaboration with some of the leading API teams around the world, as they craft their API strategy through a design workshop that we provide at Apigee. We call our point of view in API design “pragmatic REST”, because it places the success of the developer over and above any other design principle. The developer is the customer for the Web API. The success of an API design is measured by how quickly developers can get up to speed and start enjoying success using your API. We’d love your feedback – whether you agree, disagree, or have some additional