Home > Technology > Typical errors found around APIs

Typical errors found around APIs

Dear visitor,

effective immediately, we have moved to our dedicated servers in http://www.brizoma.com/

Please update your bookmarks, since we will not update this site anymore.

See you in BRIZOMA.COM


What if the source of your traffic came more from one of your APIs than the web site?

In the last months I have been confronted to intensive use of webservices and APIs. Let’s summarize common errors that should be avoided when developing -and later launching- an API-based service.

1. Assuming Everything Will Always Work

Databases fail, backend dependencies get slow, and/or someone somewhere along the line doesn’t escape output properly. The result? A nasty stack trace at the top of your API payload, which in some cases may even include production database credentials. Solution: Before you launch, kick over some dependency and see what your API does. Developers would rather have a predictable (valid XML/JSON) error message they can code for than a surprise invalid payload.

2. Poor Community Management

Sometimes we see providers expecting the API alone to attract developers. You need a good service and must communicate to developers what it is you provide. Also, along similar lines, it’s easy to ignore the developer community management, but that communication can make or break your platform. When you get developers’ attention, keep it by being responsive and helpful. Treat them like partners.

3. Not Anticipating How API Business Processes Will Scale

APIs are about bringing the scale of the Internet to bear on your business – but what if that scale actually happens? Will a manual review for user on-boarding scale if you surge in popularity? Will auditing and liability processes get in the way of enabling free access to a subset of your data? Governance is less important when the API is less used, but when transaction volume becomes significant, APIs become important to the finance and legal teams. Don’t let success lead to failure due to non-scalable processes.

4. Putting the API Under Website Domain

Case in point: twitter.com is now going to api.twitter.com for the API. The result is that they can scale the website and the API independently of each other as needed. I’ve never heard of anyone regretting the decision to split out API traffic from main website traffic, and nearly everyone to doesn’t do that at the beginning wishes they had _and_ endures a lengthy & painful process of migrating developers to the new API location.

5. Lack of Real-World Testing

You can often tell the APIs that have had some real-world use before launching, and those that haven’t. For example, an API that lists _some_ information about an object, yet needs a secondary call to get MORE information about that object. If your API requires two calls to find out everything there is to know, you and your devs will hate you for it eventually.

Build a couple of reference apps that might do something useful, even if trivial. You’ll quickly get a sense for how sane your API is when you run into those inefficient API call combinations. If you haven’t built your website on top of your API, consider doing that — or at least what it would be LIKE to do that. If your API couldn’t reproduce your website, your API needs fixing.

6. Not Anticipating Bad Behavior

1)Tactical Bad Behavior

* Inefficient client code can call an API too frequently, causing an accidental DDoS attack
* APIs can be attacked through the JSON or XML data passed as parameters or attachments;
* Attack techniques can include SQL injection, XML bombs, and shell scripts, as well as the usual social engineering and spoofing attacks.

2) Bad behavior “at scale”

* When your service is small and you have a hundred users, you may have only two bad actors. These can be pruned manually using firewall rules based on IP address.

* When your service is scaling to hundreds of thousands of users, you may have thousands of bad actors. These are placing high levels of “fake” demand on the service and can no longer be pruned manually without adding more staff dedicated just to these issues.

* To mitigate this do you apply rate limits to everyone and reduce the value of the service to good users? Do you find a way to apply policies to naturally separate patterns of use?

The anti-pattern we’ve seen here is the failure to anticipate bad behavior against your service, and then to respond either with draconian limits on use, or with intermittent systems availability as a result of dealing with the bad demand.

7. No Black Box Tests

“Many APIs have no testing at all, and those that do frequently have automated unit tests, etc. Very few have end-to-end black box tests that can be run surrounding releases. Your unit tests may pass, but if your latest push also included a web server config tweak, you want to have an end-to-end test suite to validate those changes.”

8. Not Recognizing the API as a Core Line of Business.

“The companies who succeed in the new web economy recognize that APIs are a core line of business and essential path to customers and partners. Successful media, retail and web companies often see over 50% of their traffic from their API – and companies must treat it as a product.”

9. Not Having Management on Board with the API

Like any new project, business and technology need to be lined up together including having understood and documented goals, metrics, and rewards. What higher level objectives are being met and how do these map into departmental goals for marketing, customer support, and engineering? How will these be reported to senior management and on what cadence will performance be reviewed?

10. Tunneling Errors

“The specific mistakes you see regularly are error tunnelling (sending back a “200OK” response code, even if the body of the response describes an error). GET/POST tunnelling (sending all requests through GET or POST and ignoring the other verbs (PUT, DELETE, etc). And content-types (not allowing the consumer to specify the content type they will accept). Most of the big players get it mostly right. Amazon, for example, sets a good example, whereas Flickr does not. But most API providers miss the more esoteric stuff like hypermedia is the engine of application state and ignoring caching. However, you can use an API without that stuff quite adequately. It’s the incorrect tunnelling that will hamstring you and your consumers.”

11. Not Providing a Status Page

Major players like Google have launched servies like Google Apps with little public visibility into the uptime, availability, and performance of the services themselves. This quickly changed in the wake of promises to promote transparency

http://googleenterprise.blogspot.com/2009/02/new-status-dashboard-for-google-apps_25.html

http://www.google.com/appsstatus

While some might argue this was a late response, most sites that have received some level of popularity have had to content with the “status” approach.

Examples:
http://status.twitter.com (general public)
http://dev.twitter.com/status
http://status.watchmouse.com/7617# (Twitter frame)

12.

Great article! Would love to see more on how to combat #6… for example, if a buggy client goes out to thousands of users that makes repeated calls with no throttling that’s equivalent to a DDOS attack. How to protect against this?

13.

API’s should communicate the expectations of the platforms to be integrated to all stakeholders (programmers, users, etc.)

I hate when API’s aren’t restful or they change in unexpected ways or customers think they want me to build an API on top of an API that isn’t sensible the first time.

14.

in other words, users don’t understand how misguided some APIs are, but customers have a good idea how things should be integrated… sometimes better than the API writers [:

15.

@Nicholas, at Mashery we prevent things Sam mentions in #6 by allowing limits to be applied at an individual level. We also encourage API program managers to leverage developer “classes” or “groupings”, so that n00bs can be put in a limited bucket until their application is fully baked. Once they feel they’re worthy, they can contact program managers to be put into a higher-limit (or optionally limit-free) grouping.

We also facilitate API Development Sandbox environments, so that’s another option for new adopters of the API. Granted, Sam’s comment in #3 kicks in then — managing workflows for a program that becomes popular is something many overlook.

Finally, if you want to keep the API on auto-pilot, our managed services team will proactively contact you about a developer who’s spinning out of control. We’re continuously monitoring each registered developer’s relative use over time, so if an app goes crazy, their relative use spikes, which sets off alarm bells at Casa de Mashery. We’ll work with you to identify the best course of action to help that developer get their runaway train under control, and to defend your backend from the inadvertent DDoS.

16.

That’s a great list an API developer should keep as reference.

A better title for #10 would be “Claim the API is RESTful if it isn’t”. Although there is a lot of room for discussions what makes an API RESTful, there are some clear indication that an API doesn’t follow the basic principles of a REST architecture.

On the other hand, there are other protocols like SOAP or XML-RPC where tunneling errors is perfectly ok.

17.

Real facts, i am working with FB API since last 2 years, its really bad thing that Provided API Doc is not upto the mark and contains lot of bugs like mention wrong parameter list of an API call. So that have to test before put them live.

18.

Not Having an API Status Page or Uptime Availability Performance Dashboard

19.

Not providing source code and/or command line examples: getting people started is hard and developers like to see how things work quickly otherwise they may move on and work with a different API.

20. Being fuzzy on licenses: people like to know what they’re permitted to do and if someone invests significant amount of time in developing against you’re API you should treat them like a partner (as already mentioned above) – that also means being clear about what commercial and non/commercial use means.

21. Not using standards such as oAuth for user authentication: if there are end users involved getting the authentication right is important and protocols such as oAuth help solve this. While they’re not always appropriate, use the when you can – there are good libraries emerging for most platforms and doing something equally powerful but different wont win friends!

and a last business-y one:

22. Not planning for different types of target audience: often people think of putting out an API to attract individual developers who’ll build “cool stuff” – this can certainly work but often it’s worth thinking of the medium and large partners who might be interested. This can range from your signature clients who want more access to your services, to building a broad partner network. All of these are valid – for particular APIs the target audience which loves it most might be obvious, for others this might need some exploration.

23.

How would you promote an api?

For instance, http://www.mimvi.com/corp/api_documentation.html is an API for a very very large index of all mobile apps on all platforms.

How would you suggest this get socialized?

There are quite a few things you can do to promote the API. First step would be to ensure you have a programmable web profile (which mimvi) has and then I’d say the other items fall into two categories: community related and outreach related.

Community related means focus on building a user community v’s a user base – i.e. developers and partners that are in some sense aware of each other and can cross polinate rather than many “individual” users who aren’t connected. So this means: showcasing use cases, example code, having support forums available and providing success story cases where you can from early users. Taking Mimvi as an example, going to the site it’s tough to get a sense of wether or not the API is being used by others, whether I’ll be able to get support and how to get started. I.e. its hard to know how to really engage with the provider of the API, or other users of it.

Outreach related would mean, beyond the developer resources provided build visibility which makes people go there in the first place. Some of this isn’t much different from standard marketing (videos of use cases, getting in touch with people writing about topics where an API is relevant) but some are more specific. In most cases you probably have two target issues: customers of the product itself which could benefit from the API as a value add and external third parties / developers. For the former category it often helps to have example uses of the API ready that people can understand and “adapt” to their needs rather than having to write them from scratch. For the later case, seek out the places where developers most likely to benefit are located, from stackoverflow to platform specific forums (online or specific events) and the best material is often “how to” material with real examples.

There’s a lot more too it, but hopefully this helps a little, if useful drop me an email (steve@3scale.net) and we’d be happy to help with the project you have.

24.

Here are two of my favorites:

Not Building the API First

For best results, build the API first. Then build the site on top of the API, and finally choose the parts you want to open up to the public. Sites that build the API as an afterthought are doomed.

Failing to Adequately Support JavaScript Output

Commonly known as JSON-P, JavaScript output is key to client-side mash-ups. If you don’t support it from the very beginning, enterprising operators will use tools like Pipes or YQL to get it, and you’ll have no clue what the client’s doing with it once it’s out there.

Simple things to remember about JavaScript output: allow dots and square brackets in callbacks, send content-type text/javascript instead of application/x-json, and wrap ALL responses in an HTTP 200, or else the browser won’t see them.

25.

Guys from Amazon experienced things like this a long time ago.

26.

That’s a great list an API developer should keep as reference.

A better title for #10 would be “Claim the API is RESTful if it isn’t”. Although there is a lot of room for discussions what makes an API RESTful, there are some clear indication that an API doesn’t follow the basic principles of a REST architecture.

On the other hand, there are other protocols like SOAP or XML-RPC where tunneling errors is perfectly ok.

27.

As a follow-up to #4 (Putting the API Under Website Domain), I would also look at hosting the API on a different subdomain from the main site (e.g., for Twitter it could be twitterapi.com). This keeps login or other cookies isolated from the API calls and usually lets you have a more open crossdomain file for Flash/Silverlight apps.

On the business side, and similar to what Steven Willmott mentioned, I would prep for unexpected users of your API, and how you plan to deal with them. You may have visions of really sexy mashups and cool mobile apps, but when your data is powering spammy sites like “Palm Beach Hotels”, you’ll want to be prepared.

28.

Yes a lot of these points are very true. Limiting the number of calls a user can make, debugging the api extensive, having a lot of feedback before making the api public. but there will always be flaws

29.

Creating complicated API… And then not quite understanding how to resolve the problems that arise.

30.

Returning different data than your website does

For example the digg.com website search returns different (and better) results than the digg api does.

31.

I fully agree with items #8 and #9. This is often the business side of Web 2.0 that is not always fully understood by C-level executives.

There a quote that I like from Caterina Fake (Flickr), mentionned by Oren Michels (Mashery) in one of his presentations: “What is an api? Biz dev 2.0, I call it”.

The video from BestBuy about their Social Technology Strategy is also very envisioning (http://www.youtube.com/watch?v=whzN-7uCiZw).
APIs basically enable remix and Lean Business Development.

32.

API mistake #11: not eating your own dogfood.

It’s best to build your own websites and mobile apps as clients that consume the exact same API that is available to your developer community.

Advertisements
Categories: Technology
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: