APIs are delivering on their promise
October 3, 2012 —
(Page 5 of 6)
Related Search Term(s): APIs
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.”