You can learn a lot from studying what other API providers are doing. That’s why this book is useful; you will learn about what API makers are doing—at least from the outside.

What are some great examples to study? Flickr is a good one obviously. Recently, I’ve come to appreciate the Google documentation as being really good too. It has a lot of ­copy-­and-paste code, plenty of ­getting-­started sections, and the API references. Often there are API kits in a number of languages; of course, a lot of time and energy went into creating this documentation.

Moreover, if you are a little player, consider making your API look a lot like those of the big players. For example, 23hq.com, a ­photo-­sharing site, decided to mimic Flickr’s API instead of developing its own:

http://www.23hq.com/doc/api/

That enabled Dan Coulter to support that API in addition to Flickr’s API in phpFlickr:

http://phpflickr.com/phpFlickr/README.txt

If 23hq.com had built its own API, it would not be able to leverage the work of the ­much-­larger Flickr development community.

Whether the creator of an API is flattered or irritated by the sincere imitation of the API by other players surely depends on context. Consumers of the API, however, will be all too happy to not have to learn yet another API to access essentially the same functionality from different web sites.

You need to consider two distinct audiences when deploying a public API. The first is the direct audience for the API; this is the developer community, which includes those who will directly program against your API. The second is the indirect audience for the API but perhaps a direct audience for your web site: the possible audience for those ­third-­party applications. Remember that although you have a direct audience in the developers, you are ultimately trying to reach the second, potentially much larger, audience.

Good documentation of the features, the API, data formats, and any other aspect of the web site makes it much easier to understand and recombine its data and functionality. You should clearly document the input and output data expected. Do you provide pointers to schemas or ways to validate data? Documentation reduces the amount of guesswork involved. Moreover, it brings certainty to whether a function you uncover through reverse engineering is an official feature or an undocumented hack that has no guarantee of working for any length of time.

Why, for instance, do I recommend people using the Flickr API as a starting point (and maybe for the ­long term)?

The Flickr API Explorer is excellent and should be more widely emulated. It lets you invoke a method in the browser and see the response. The documentation lists not only the methods but also the input parameters and error codes. The great thing is that you can read the documentation and try something. Moreover, the Flickr API Explorer shows you a URL coming out of the REST API that you can copy and paste elsewhere.

Use the techniques from Chapters 7 and 8 to remix your own site to see how mashable your site is and how well your API works. Review Chapter 11, and read in the feeds from your site into Yahoo! Pipes or the Google Mashup Editor.

You might be using your own APIs in an Ajax interface—but it’s helpful to think like a mashup creator who is coming to your site for the first time and who will use more generic tools to analyze your site. It’s interesting to see how your site looks from that point of view.

You can go further by extrapolating techniques from usability testing (http://www.useit.com/alertbox/20000319.html) to testing your API, instead of the UI of your web site. For instance, you could recruit a group of developers and give them a problem to be solved using your API. See what these developers actually do. Make changes to your API in response to feedback.

A public API for your web site does not have to be something you build only for others. Rather, it can be the natural outcome of creating a scalable and adaptable web site. One architectural pattern that has proven effective in creating such web sites—that of ­service-­oriented architectures—is to decompose functionality into independent, ­fine-­grained components (called services) that can then be stitched together to create applications. By defining clear interfaces among the services, one can change the internal workings of individual services while minimizing the effect on other services and applications that consume those services. It is this loose coupling of the components that makes the whole web site scalable.

With a set of granular services in place, you as a content producer have the building blocks of a public API. You can always start with a private API—which many Ajax interfaces demand. That way, you can decide to roll out a public API. (For instance, you use Firebug to study how the Flickr API is often being called by Ajax parts of the Flickr interface.)

If you decide to go for an API, make APIs an integral part of your site. The fact that the system depends on the APIs ensures that the APIs aren’t just throwaway parts of the system. This provides assurance that the API is an integral part of the system.

For more insight into how service orientation benefits Amazon.com, which is a major consumer of its own services, read an interview with Werner Vogels, CTO of Amazon.com:

http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=388

From Chapters 6 and 7, you know that REST is much easier for your users to get started with. (Amazon S3 in Chapter 16 provides another concrete case study of REST.) The use of REST and not just SOAP or ­XML-­RPC lowers the barrier to entry. With REST, you can see results in the web browser without having to invoke a SOAP client (which is bound to be less available than a web browser). There’s a strong argument to be made that by building a good RESTful human web API, you are already building a good API:

http://blog.whatfettle.com/2007/01/11/good-web-apis-are-just-web-sites/

However, if your primary developer audience is oriented toward enterprise development and is equipped with the right tooling, you might have to prefer SOAP/WSDL over REST. Remember that SOAP without WSDL isn’t that useful. And if you do SOAP, be strictly observant of the version you are using.

Again, if you build an abstraction layer underneath, you might be able to handle multiple transport protocols. Your favorite programming frameworks might autogenerate REST or SOAP interfaces for your web application.

If you build Atom 1.0 feeds, you’re already on the road to building an API. Recall that there’s plenty of prior art to be studied in the Google GData APIs if you want to go down this road. (Chapter 7 has a study of GData; Chapter 15 on the Google Calendar API is another study of GData.)

It’s nice to have both the raw XML web services and the ­language-­specific API kits. In theory, according to the argument of REST or the SOAP/WSDL camp folks, having the right web services should obviate the need for ­language-­specific API kits. My own experience is the opposite. Sure, the Google GData APIs (see Chapters 7, 8, and 10) are RESTful, but having PHP and Python libraries is very useful. Even with WSDL, a ­language-­specific API kit is handy.

Ideally you would have API packets for every possible language. Of course this is not practical—and not even the largest companies such as Google provide that many API kits. The priority is to have a good ­well-­documented API. After that, I would say if you can put out an API kit in the language that you use ­in-­house, that’s already a great service. Google puts out API kits for its ­in-­house languages. Microsoft puts out API kits in the languages it supports. Beyond that you need to talk to your potential developers and see what’s important to them. (It’s nice to have API kits that cover a range of languages.) Remember you don’t have to develop all the API kits yourself—Flickr doesn’t develop that many but provides a place to publicize them and promotes those API kits in the community of developers.

If you can provide both, it’s nice to have a ­server-­side language API kit and JavaScript API kit for ­client-­side access.

Note that for better or worse, it’s very easy for developers to ignore error handling. You have to encourage them to handle errors. It starts with having good documentation of errors.

I’m of mixed minds about whether to embed the error in the XML body or as an HTTP response code. HTTP error codes are a standard way of dealing with errors, but it’s not necessarily the easiest thing for new developers to understand. At any rate, in SOAP you can do fault handling in the fault code of the SOAP body. In ­XML-­RPC, it’s dealt with in the error body. I might suggest that even if you put error codes in the response body that you use the HTTP error codes as a starting point to build your own error response functionality.

	Note
	The specification for the latest version of SOAP (1.2) now provides guidance on how to use the various 2xx, 3xx, 4xx HTTP status codes.[151]

It’s nice to have multiple ways of getting content in and out of an application. For example, Flickr has many ways to upload photos: the web interface, the desktop Uploadr, the API, and e-mail. Even so, some people have requested FTP and some type of mass downloading. Flickr doesn’t offer FTP capabilities, but some people have worked to simulate it:

http://blog.wired.com/monkeybites/2007/06/upload_to_flick.html

For calendaring, you’ll see the use of iCalendar and CSV in Chapter 15. In Chapter 13, you’ll see how the proliferation of KML and geoRSS has been a boon.

As a consumer of APIs, I advocate support for all the elements available to users in the UI—and then some. It’s frustrating for mashup creators to not be able to do something in the API that is clearly allowed by the user interface. There are sometimes good reasons to not enable certain actions in the API—but apart from such reasons, having a complete API is really helpful. As you saw in Chapter 6, there is a strong overlap between the capabilities of the Flickr API and the UI. There are some discrepancies between the API and UI—they got close but not an exact alignment.

You might consider adding an API to specifically enable searching of your web site. See Chapter 19 for how OpenSearch can then be used to integrate your web site’s search functionality in other frameworks.

APIs, like all programming artifacts, are likely to change. Instead of having only one version of your API that can change, support multiple versioning of your API. That doesn’t mean you will have to support every version indefinitely. Publishing a timeline for when you plan to retire a specific version of your API and documenting changes between versions allows the consumers of your API to make an orderly transition and adapt to changes in your API. Flickr doesn’t explicitly version its API; for an example of an API with support of multiple versions, see the following:

http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=118

A vibrant and active community makes a lot of mashup work practical. When making mashups, there are things that are theoretically possible to do—if you had the time, energy, and resources—but are practically impossible for you as an individual to pull off. A community of developers means that there are other people to work with, lots of examples of what other people have done, and often code libraries that you can build upon.

You should have a clear ToS for the API—see Chapter 6 for a discussion of the ToS for the Flickr API. Don’t try to be too controlling of your API. For instance, you might be tempted to forbid a user of your API from combining data from your site with that of other sites, such as those of your competitors. That’s very much against the spirit of mashups and is likely to antagonize your developers. I would argue that asking a user of your API to reference your web site is a good balance between the interests of the API consumer and API producer.

There are a lot of issues when it comes to establishing a policy for your API—but one is worthy of special consideration is that of commercial use. It’s not uncommon to make a basic distinction between the commercial and noncommercial use of an API, especially if you are not charging for the noncommercial use of an API. It’s useful to reflect on how Flickr and others handle the distinction in the context of your own business model. Remember, though, that it’s sometimes tricky to distinguish between commercial and noncommercial use; you will need to set up a process to make such a distinction.

A ­service-­level agreement formally spells out the level of service a user can expect from a service and the remedies for failures to meet the expected level of service. It’s debatable whether most SLAs are of much practical use. What I really want is perfectly reliable service. Can any remedy offered by most service providers adequately compensate for disappointing that desire?

Nonetheless, as a user, I find that a thoughtfully constructed SLA reassuring because it gives me a sense of the level of reliability to expect from a service provider. A specific measurable target of performance is likely better than none at all. As an example, Amazon.com recently introduced an SLA for its S3 service:

http://www.amazon.com/b?ie=UTF8&node=379654011

Encourage the users of your API to consume compute cycles and bandwidth parsimoniously—most developers will want to cooperate. Document your expectations on the limits you set for the total volume or rate of API calls. Error messages from your API to indicate the throttling of API calls are very useful to consumers of an API.

When developing an API, it’s not unusual for you to issue keys to developers. However, tracking usage by the key alone is sometimes insufficient to manage the level of usage—keys are often leaked. You might track API usage based on a combination of key and originating IP address.

Both server- and ­client-­side caching help with the performance of an API. You will want to help the users of your API to cache results properly. It’s extremely useful to have APIs that tell you when something has been updated and to return changes in the state of the data since a given time.

If you want to open up your site to deeper remixability, you might even publish the source for your web site. Users will then have the option of studying the source directly should reverse engineering—or reading the relevant documentation—not give you the answers they need.