APIs are delivering on their promise

Alexandra Weber Morales
October 3, 2012 —  (Page 5 of 6)
The API-first approach aligns around actions, which allows for reusability, simultaneous iteration cycles for front and back ends, and ensures that the app is data-driven.

If API-first development takes off, API makers and consumers are still wise to heed Pamela Fox’s advice. Too often, an API is passed over because its community pages are empty and support is nonexistent. Developers do want hand-holding when they use your API. That includes not only easy signup, but also guides, searchable reference materials, SDKs, pricing and clear terms of service. There has to be a community: a forum, blog, social media presence, e-mail list and an app gallery. There has to be evangelism and great support. And all of it can feed back into the API.

“Does API design impact support? Yes it does,” said Musser. “Take a look at Twilio’s error response. There’s a lot of detail in this 400-level response. The provider gives you, the developer, a link to where to go to research this error message.”

Poor error-handling is last, in fact, on Musser’s top 10 API worst practices, which are:

10. Poor error handling
9. REST APIs that ignore HTTP rules
8. Exposing your raw underlying data model
7. Security complexity
6. Unexpected and undocumented releases
5. Poor developer experience
4. Expecting an MVC framework automatically means you have a great API
3. Assuming that if you build it, they will come
2. Inadequate support
1. Poor documentation

“If you expect that because you use Rails you have an API, you don’t. What that is doing for you is you are exposing your raw data model. You have to work back from your use case that developers have,” said Musser.

DocuSign’s Mike Borozdin, director of integration development, recently blogged about creating a “Rubik’s Cube of development scenarios. We heard that while we had the most comprehensive set of functionality, it was sometimes hard to figure out how to get started. So we created a grid of the most popular scenarios that our customers and partners implement. When you click into a scenario, you get a high-level overview of the sequence of calls that your program will need to do. If you click on one of the steps, you will see a code sample with a detailed explanation for the key parameters. The feedback from our initial testing is that it’s much easier to get going and incredibly fast.”

Related Search Term(s): APIs

Pages 1 2 3 4 5 6 

Share this link:


10/08/2012 02:41:43 PM EST

Excellent article! With so many sites, popping up to assist non-developers to create data integrations for syncing and mashing data, it's surprising that no one has developed a site that focuses on documentation. With such poor tech writing, and the job falling onto developers, I have seen such terribly written documentation. I could care less about examples - I just want well, written documentation. Here's a great example of a use case for Zapier, a site that let's you easily create intregrations to push data between apps -

United StatesMichael

Zeichick’s Take: Open up your APIs!
APIs need to be compelling and easy to use to get developers on board Read More...

News on Monday  more>>
Android Developer News  more>>
SharePoint Tech Report  more>>
Big Data TechReport  more>>



Download Current Issue

Need Back Issues?

Want to subscribe?