The 5 laws of API dates and times

Repost from APIUX.com: http://apiux.com/2013/03/20/5-laws-api-dates-and-times/

In short:

Law #1: Use ISO-8601 for your dates
Law #2: Accept any timezone
Law #3: Store it in UTC
Law #4: Return it in UTC
Law #5: Don’t use time if you don’t need it

Funny Gifs on API

http://apijoy.tumblr.com/ has a couple of funny Gifs on API, for both API consumers and producers. Visit for a laugh.

My favorites:

when i realize a competitor asked for an API key


what i feel when i use a REST/JSON API


When I find code samples in API documentation

Should API support Cross Site Scripting - CORS, JSONP?

One of the most requested feature for API provider would be support for CORS or JSONP.

This usually comes from client side developers using Javascript or Flash, which has a strict same origin policy (a form of security).

One of the very good guide comes from Apigee:

1.       Always make it possible for your API to return JSON.

2.       Support JSONP as much as you can (since you can't use it to upload data that doesn't fit in the URL) and leave it up to the users of your API to assess the security risks

3.       Support CORS by returning the Access-Control-Allow-Origin header on all API responses and implementing the OPTIONS verb as specified in the CORS spec.

4.       If you do the above your API will also support UMP.

5.       Return a crossdomain.xml and clientaccesspolicy.xml file from the top level of your API domain for Flash and Silverlight clients.

And looks like CORS is the trend. You could do JSONP too, but that was more of a hackaround. Youtube, Dropbox, etc are all implementing CORS.

Enable CORS!

API Design is about Naming

API design is about naming.

A lot of times, it is about choosing a right name, and making sure they makes sense and is consistent throughout.

It is like a little API language of itself, as quoted by Joshua Bloch.

Survey of API Pain Points

Want to know the biggest headaches when in comes to API integration?

Read the survey results from YourTrove, who ran the survey on Hacker News.

Not surprisingly, the pains are:

• Poor documentation (how you loathe poor documentation)
• OAuth (oh wow, do you hate OAuth)
• Poor error handling
• Lack of example code
• Lack of test environments
• Lack of standardized libraries across languages
• APIs that change/break frequently (huge shout out to Facebook here, like you're surprised)
• Normalizing data to match internal data structures
• Line between use and abuse
• Arbitrary throttling (differences between services)
• Differing standards (REST v SOAP v XML-RPC, XML v JSON v POST, versioning v not, etc.)
• Getting services to talk to a dev machine behind a firewall       

Guides for iOS library design

Matt Gemmell had written 25 good rules for API design, specifically for developers writing iOS/Mac libraries, frameworks, or resuable components.

Standard for SMS/Network API

GSMA does have a mandate on how network APIs should be designed.

For example, this is what they mandated for SMS Restful API.

AFAIK, Simplified does follow the "rules". But does it do any good?

Self-Service is Key to Success

Twilio CEO Jeff Lawson argued that two of the ways APIs can be successful in courting new developers are by being self-service and by having a freemium option.

I couldn't agree more.

Developers should be able to visit your website and get started right away, without paying a thing first. And, the documentation must be readable.

Source: API Evangelist

The Trend is JSON as Response Format

Many API providers are adopting JSON as the standard, and only, format in API.

Take twitter trends API for example, which they have announced they will switch the API to JSON only.

The reason quoted is that the usage for XML format is significantly low. So if you are designing an API today, you can consider support just JSON. That's the trend.

Lessons from Stack Exchange

Kevin Montrose has posted on the history of Stack Exchange API and a subsequent post on the mistakes.

One cool thing about their API design is that they have mandated using Gzip in their response. The reason is that they felt compression/decompression using CPU resources is cheaper than bandwidth. 

Refer to their gzip usage.

Vectorized Requests in API

Vectorized requests is an API technique that is becoming more popular these days. It is a way of requesting a multiple resources in a single http request

For example, you can request multiple users with the following:

http://myapi.com/users/1001;1002;1003/

These technique is seen in twitter API and StackExchange API.

It is an efficient technique if your API usually results in developers calling the same resource multiple times. Why make 100 request for 100 users, when you can make just 1 request?

9 API Lessons from Foursquare Engineering Team

Foursquare is going to sunset their v1. With their new v2, they have blogged about their experience in designing API – Woulda, coulda, shoulda.

They are very valuable lessons for anyone designing API.

I sum up the 9 lessons:

1. OAuth and HTTPS-only: OAuth is easy to implement on both server and client. Offloading encryption to HTTPS is a no brainer.
2. REST lite: Resource-ful for key objects, with associated actions. Avoid deeply nested URLs. Avoid having multiple ways to do the same thing. Use only POST and GET. Avoid PUT and DELETE.
3. Generic structures and indirection: Wordier and more explicit JSON, but less likely to break with future changes.
4. Documentation: API explorer is good. It is worth hacking up a simple documentation generation system for the endpoints.
5. Timestamps as seconds since epoch: Not human-readable, but so easy to parse, and nobody has complained.
6. Versioning: Sometimes, you need to take back some decisions, sunsetting certain a old version, and out with a new version. It is needed.
7. Category representation: Should have
8. Object consistency and level of detail: Having a "compact" and "full" representation
9. Envelope: Wrap responses in a meta block