What should a developer know before building an API for a community based website?

Question

What things should a developer designing and implementing an API for a community based website know before starting the heavy coding? There are a bunch of APIs out there like Twitter API, Facebook API, Flickr API, etc which are all good examples. But how would you build your own API?

What technologies would you use? I think it's a good idea to use REST-like interface so that the API is accessible from different platforms/clients/browsers/command line tools (like curl). Am I right? I know that all the principles of web development should be met like caching, availability, scalability, security, protection against potential DOS attacks, validation, etc. And when it comes to APIs some of the most important things are backward compatibility and documentation. Am I missing something?

On the other hand, thinking from user's point of view (I mean the developer who is going to use your API), what would you look for in an API? Good documentation? Lots of code samples?

This question was inspired by Joel Coehoorn's question "What should a developer know before building a public web site?".

This question is a community wiki, so I hope you will help me put in one place all the things that should be addressed when building an API for a community based website.

Solution

If you really want to define a REST api, then do the following:

1. forget all technology issues other than HTTP and media types.

2. Identify the major use cases where a client will interact with the API

3. Write client code that perform those "use cases" against a hypothetical HTTP server. The only information that client should start with is the response from a GET request to the root API url. The client should identify the media-type of the response from the HTTP content-type header and it should parse the response. That response should contain links to other resources that allow the client to perform all of the APIs required operations.

   When creating a REST api it is easier to think of it as a "user interface" for a machine rather than exposing an object model or process model. Imagine the machine navigating the api programmatically by retrieving a response, following a link, processing the response and following the next link. The client should never construct a URL based on its knowledge of how the server organizes resources.

4. How those links are formatted and identified is critical. The most important decision you will make in defining a REST API is your choice of media types. You either need to find standard ways of representing that link information (think Atom, microformats, atom link-relations, Html5 link relations) or if you have specialized needs and you don't need really wide reach to many clients, then you could create your own media-types.

5. Document how those media types are structured and what links/link-relations they may contain. Specific information about media types is critical to the client. Having a server return Content-Type:application/xml is useless to a client if it wants to do anything more than parse the response. The client cannot know what is contained in a response of type application/xml. Some people do believe you can use XML schema to define this but there are several disadvantages to this and it violates the REST "self-descriptive message" constraint.

6. Remember that what the URL looks like has absolutely no bearing on how the client should operate. The only exception to this, is that a media type may specify the use of templated URIs and may define parameters of those templates. The structure of the URL will become significant when it comes to choosing a server side framework. The server controls the URL structure, the client should not care. However, do not let the server side framework dictate how the client interacts with the API and be very cautious about choosing a framework that requires you to change your API. HTTP should be the only constraint regarding the client/server interaction.

Comments

[Thellimist]

The client should never construct a URL based on its knowledge of how the server organizes resources could you clarify this?

[Darrel Miller]

@Thellimist If a client has knowledge that it can find a customer at /customer/bob it should not assume that it can find Bob's orders at /customer/bob/orders. The client should discover where Bob's orders are by looking for a link in a returned representation that says where Bob's orders are.

[Thellimist]

Isnt that Api documentations job?

[Darrel Miller]

@Thellimist If you are doing a basic HTTP API, then yes. If you are building a REST API, then no. REST APIs use hypermedia to discover resource URIs.

[du369]

@DarrelMiller I don't quite understand this line: it should not assume that it can find Bob's orders at /customer/bob/orders. What does it imply? Does it just means the client should not try to construct the links to the orders resource but is aware of its existence? Or it means the client should no idea at all of what resources the rest api provides? (not only the links, structure, but also the very existence) If it is the later case, how can a client supposed to understand the meaning of orders? A machine clearly doesn't understand that, does he?

[Darrel Miller]

@du369 Clients that are hypermedia driven can have prior understanding of link relations. Therefore when a client finds a link in the customer representation that has a link relation type that the client knows points to orders, it can discover the orders resource. HTML pages with rel="stylesheet" are an obvious example of this. The client has no prior knowledge the HTML page has a stylesheet or what its URL is.

[du369]

@DarrelMiller So if I am understanding you correctly, the following is what happens in the case of rel=stylesheet. When a browser receives a response, it learns that the response is a html page if the media type(Content-Type header) is text/html. And the browser, as a machine client, understands what stylesheet means (it can apply the css style) because it has prior knowledge of link relation stylesheet which is defined in the published_specification.

[du369]

@DarrelMiller Q) So there exists a central "media type registration center"? Q) On this page, the author did something like linkTo(methodOn(EmployeeController.class).all()).withRel("em‌​ployees")). Is employees a legal Extension Relation Type? Or is it allowed to add link relation at run time? Q) If I wish to write a client that understands what orders means (so that a machine can analyze the orders, or even place an order by itself etc.), does it means that I have to register a new media type and explicitly define a orders link relation?

[Darrel Miller]

@du369 Yes. It is here Extension link relation types should be URIs. Otherwise they should be registered here To the last question, the answer is not necessarily. But I don't have enough characters to explain here.