{"id":23703,"date":"2023-05-09T01:32:24","date_gmt":"2023-05-09T01:32:24","guid":{"rendered":"https:\/\/www.booksofall.com\/in\/?post_type=product&p=23703"},"modified":"2023-05-09T01:32:24","modified_gmt":"2023-05-09T01:32:24","slug":"web-api-design-crafting-interfaces-that-developers-love","status":"publish","type":"product","link":"https:\/\/www.booksofall.com\/in\/web-api-design-crafting-interfaces-that-developers-love\/","title":{"rendered":"Web API Design – Crafting Interfaces that Developers Love"},"content":{"rendered":"

Introduction<\/h2>\n

If you\u2019re reading this, chances are that you care about designing Web API<\/a>s that developers will love and that you\u2019re interested in applying proven design principles and best practices to your Web API.<\/p>\n

One of the sources for our design thinking is REST<\/a>. 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.<\/p>\n

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<\/a>.<\/p>\n

We call our point of view in API design \u201cpragmatic REST\u201d, 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.<\/p>\n

We\u2019d love your feedback \u2013 whether you agree, disagree, or have some additional practices and tips to add. The API Craft Google Group<\/a> is a place where Web API design enthusiasts come together to share and debate design practices \u2013 we\u2019d love to see you there.<\/p>\n

Are you a Pragmatist or a RESTafarian?\u00a0<\/span><\/h2>\n

Let\u2019s start with our overall point of view on API design. We advocate pragmatic, not dogmatic REST. What do we mean by dogmatic?<\/p>\n

You might have seen discussion threads on true REST – some of them can get pretty strict and wonky. Mike Schinkel sums it up well – defining a RESTafarian as follows:<\/p>\n

\u201cA<\/i>\u00a0RESTifarian\u00a0is a zealous proponent of the REST software architectural style as defined by Roy T. Fielding<\/a> in Chapter 5 of his PhD. dissertation at UC Irvine. You can find RESTifarians in the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST \u2026\u201d<\/i><\/p>\n

Our view: approach API design from the \u2018outside-in\u2019 perspective. This means we start by asking – what are we trying to achieve with an API?<\/p>\n

The API\u2019s job is to make the developer as successful as possible. The orientation for APIs is to think about design choices from the application developer\u2019s point of view.<\/p>\n

Why? Look at the value chain<\/a> below \u2013 the application developer is the lynchpin of the entire API strategy. The primary design principle when crafting your API should be to maximize developer productivity and success. This is what we call pragmatic REST.<\/p>\n

\"\"<\/p>\n

Pragmatic REST is a design problem\u00a0<\/b><\/p>\n

You have to get the design right, because design communicates how something will be used. The question becomes – what is the design with optimal benefit for the app developer? The developer point of view is the guiding principle for all the specific tips and best practices we\u2019ve compiled.<\/p>\n

Nouns are good; verbs are bad<\/h2>\n

The number one principle in pragmatic RESTful design is: keep simple things simple.<\/p>\n

Keep your base URL simple and intuitive<\/b><\/p>\n

The base URL is the most important design affordance of your API. A simple and intuitive base URL design makes using your API easy.<\/p>\n

Affordance is a design property that communicates how something should be used without requiring documentation. A door handle’s design should communicate whether you pull or push. Here’s an example of a conflict between design affordance and documentation – not an intuitive interface!<\/p>\n

A key litmus test we use for Web API design is that there should be only\u00a02 base URLs per resource<\/b>. Let’s model an API around a simple object or resource, a dog, and create a Web API for it.<\/p>\n

The first URL is for a collection; the second is for a specific element in the collection.
\n\/dogs\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0\/dogs\/1234<\/span><\/p>\n

Boiling it down to this level will also force the verbs out of your base URLs.<\/p>\n

Keep verbs out of your base URLs<\/b><\/p>\n

Many Web APIs start by using a method-driven approach to URL design. These method- based URLs sometimes contain verbs – sometimes at the beginning, sometimes at the end.<\/p>\n

For any resource that you model, like our dog, you can never consider one object in isolation. Rather, there are always related and interacting resources to account for – like owners, veterinarians, leashes, food, squirrels, and so on.<\/p>\n","protected":false},"excerpt":{"rendered":"