Friday, September 26, 2014

How to create a Web API no one wants to use: Exercises

Introduction to this blog series


Later this year, Netflix will be closing their public APIs. Twitter and Google have already restricted their APIs. Despite prominent tech-companies making drastic changes to their APIs, the number of APIs keeps growing steadily. Suddenly, everyone has a Web API. Your car has one, Chuck Norris has one, and worst of all, tech-companies with no focus on quality whatsoever has one. And who are using these APIs? Most likely, no one.
This blog series will take you through the pitfalls of creating a Web API. From a developers perspective, what mistakes will result in no one wanting to use your API?

Part 1: URI Design
Part 2: HTTP Verbs
Part 3: HTTP Status Codes
Part 4: Result formatting
Part 5: Versioning
Exercises

Exercises


Earlier this week I presented my "How to create a Web API no one wants to use" talk at Code Pub Oslo. Code Pub Oslo is a meetup for female developers, a very inspiring event! The organizers asked me to create a set of exercises to go with the presentation, and here's the result.

Exercise 1: URI Design


Imagine you have an API with the following endpoints:

EndpointDescription
…/books/Returns all books
…/books/id/5Returns the book with ID=5
…/author/Returns all authors
…/author/3/booksReturns all books written by the author with ID=3

a) Can you spot any inconsistencies in this API? How would you fix them?
b) Can you redesign the API so that the URIs are hackable?
c) Can you think of an alternative way of filtering the books on author?

Exercise 2: HTTP Verbs


a) Which of these methods are safe?
i. Registering a new user
ii. Retrieving the weather forecast for tomorrow
iii. Cancelling an order
iv. Removing a picture

b) Which of these methods are idempotent?
i. Registering a new user
ii. Retrieving the weather forecast for tomorrow
iii. Cancelling an order
iv. Removing a picture

c) Which verb should you use for the following methods?
i. Registering a new user
ii. Retrieving the weather forecast for tomorrow
iii. Cancelling an order
iv. Removing a picture

Exercise 3: HTTP Status Codes


Which status code should you return in each case?
a) The client asks for a record that does not exist
b) The client posts invalid data
c) There was a technical error in the API
d) The client creates a new record
e) The client calls an asynchronous method

Exercise 4: Result Formatting


You are developing an API for a customer who wants to support both JSON and XML results. Which type of result formatting should you go for?

Exercise 5: Versioning


a) You are developing an API for a customer who wants the version to be an optional part of the URI. Which versioning method should you use?

b) What if the customer wanted the client to specify both the version and the result format as part of a header?

c) Can you give an example of how such a header would look?


No comments:

Post a Comment