Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Reuse of components in development of software program are always exposed through the API's. Most of the products in today's world (such a facebook, google, .Net, JDK, ...) provide API's to reuse their components without being actually coding from the stratch. Also API's provide a huge high-level abstraction to the under lying components.

My question is about the usability of these API's. Certainly, in all API's there are Obstacles. Obstacles can be

  • skill sets,
  • resources,
  • Documentation of the API's
  • the API itself.

What do the programmers think the real obstacle are? List few of your opinions.

To Question this here: Being a developer I investigated the obstacles when using 3rd party API's, one such is Highcharts. Though I have strong points why Highchart libraries are great compared to other Javascript visulization libraries (not comparing it with Google visulization API's) I found myself lost with the usability of the charts when going through their API docs at the very beginning. Indeed, their support forum is good to get your questions answered.

Developers uisng API's - most of the time - do not (sometimes, need not) understand the design intents of the API, architecural design and the decisions made during the development of the API.

Also, what will be your suggestions to make better API that will reach to large set of developers?

I'm not entirely sure about the friction of learing new API's.

PS: This may not be a constructive answer. But I am sure I am communicating with real developers on this site.

share|improve this question

5 Answers 5

Speaking from experience - I think the biggest challenge faced when learning a new API is finding relevant examples. Documentation about individual function calls or RESTful resources is one thing, but actually having good examples is invaluable.

Sadly, I find a lot of libraries either have no documentation, or just have a short bit of text attached to each function with a brief description. Example code is almost always more beneficial in terms of understanding than an abstract description of the function in question.

e.g. with Microsoft's Windows API, often you need to get a handle from one resource, pass it to another, than pass it to yet another. There's no one place that describes this sequence - so you have to jump around between multiple pages of documentation.

I'm not saying examples replace documentation; they augment it. Just like a picture says more than 1000 words, an example can show how 1000 pieces of the API puzzle fit together.

share|improve this answer
Yes and no. An example seldom gives you the bigger picture, nor does it tell you what else is there. Examples are fine as quickstart cookbooks, but if you're doing anything nontrivial, you need documentation. –  tdammers Jun 19 '11 at 9:52
Good example snippets are invaluable - certainly when an API involves use of multiple interconnected calls (rather than just a single call). e.g. with Microsoft's Windows API, often you need to get a handle from one resource, pass it to another, than pass it to yet another. There's no one place that describes this sequence - so you have to jump around between multiple pages of documentation. I'm not saying examples replace documentation - they augment it. Just like a picture says more than 1000 words - an example can show how 1000 pieces of the API puzzle fit together. –  Steve Mayne Jun 19 '11 at 9:55
Fair enough. Often examples are the best way to illustrate what the documentation explains. –  tdammers Jun 19 '11 at 9:56
I've added that to the answer - I probably should have made it clear that I don't propose examples replace other docs. –  Steve Mayne Jun 19 '11 at 9:58
I agree, that's why Oxygen documentation or Java documentation is often depressing –  Marco A. Jun 19 '11 at 18:26

To me, three things are of importance when I'm trying to get familiar with an API:

  • Does it have complete and accurate documentation? If the documentation is incomplete, it's hard to understand the whole thing, especially when the interface has limited self-documenting capabilities such as a RESTful protocol. If it's inaccurate, it means I have to not only read the documentation, but also do a part of the API developers' work (test and document the thing).
  • Is it reasonably correct, complete, and bug-free? By that, I mean that it covers the full scope of the problem domain, so that the structure of the interface mirrors the structure of the problem domain. If the problem domain isn't fully covered, chances are I won't be able to do what I need to do. If it's covered incorrectly, I'll hit edge cases and other problems down the road, and I'll have to spend considerable amounts of time working around the mistakes. And of course, if it's seriously buggy, I have to work around that too.
  • Does it use applicable standards? An API that reinvents the wheel or insists on doing things differently almost never has good reasons to do so (with a few notable exceptions). Violating standards means I can't use my standards-compliant tools, and instead I have to write my own interfacing code. Examples include SOAP interfaces that don't implement the SOAP standard correctly, APIs that produce malformed XML, functions that choke on perfectly valid XML, etc. Choosing the wrong tool for the job also belongs in this category.

Documentation is the most important one, but there's one exception: If I can read the source code, and it's written in a way that makes it easy to understand what's going on, then the source code can double for documentation.

share|improve this answer
Agreed! Examples often emerge as a key learning resource. One of the things that I struggle with is trying to figure out when there’re multiple ways of doing something. Which one is more appropriate? To resolve such questions I find code examples support several different learning activities, such as understanding the purpose of the library, its usage protocols, and its usage context. So in my experience always resources available to learn an API are more important. Poor documentaion hinders the API learning progress. –  Ashwin Jun 19 '11 at 12:28

Off the top of my head, here's a few that often steepen the learning curve. I live in the Java world, so the examples are from there.

One is unintuitive abstractions. Sometimes the API turns out not to work exactly as you expected. It's all solid and correct, but designed in a way that does not exactly correspond to your way of thinking. You may need to take a step back, stop cranking out code and spend a while trying to get in the authors' shoes and understand their intent.

That's what I encountered with Clojure which was my first contact with functional programming. It all makes perfect sense, but takes time to learn the abstractions and idioms.

This can also happen when you're locked in on one abstraction because that's what you've always been doing, and you encounter a device or interface that's completely different. For instance, how do deal with a device that has no file system, no keyboard and no mouse? That's a major change! And they're here today, but no-one did that 5 years ago. Google for Neal Ford's "Abstraction Distractions".

Another is how much of the API you're exposed to from the very beginning. Let's have a look at two tools. In order to get the most trivial hello world app running with Spring Web MVC, you have to grab a whole lot of libraries and link together a DI container, configure a front controller in web.xml, set up the controller and beans in some dispatcher-servlet.xml, configure some view resolver and whatnot. That's a lot of work!

On the other hand, have a look at Git. You can start using it by spending 15 minutes on the first tutorial and learning some 5 - 10 commands. That's enough for most of the work. But if you need more or want to streamline your process, there's tens and tens more. However, you're never forced to understand it all from the very beginning. This quality is called onionskin API.

Another is scarcity of documentation and poor examples. What I think is the best is a set of tutorials that follow the onionskin approach. Show something very simple to get you started, and then uncover next layers. There's nothing more off-putting than generated Javadoc and examples that expose you to all the gory details and use a ton of dependencies (like a database for a web app lib).

It's also bad if the documentation follows something as unimportant as syntactic sugars, but fails to explain the principles and "whys". When I learn a build tool, my first goal is not to learn 10 ways to do one thing in Groovy, but to understand its conventions and high-level approach to the problem. I expect it on all levels - from the very first description of the API to more advanced topics.

Sometimes there is a fervent community of very productive magicians that can do wonders because they studied the source, are demigods or simply have invested enough time. However, the less advanced have little resources to get started and guide them on their road to mastery. It can be very depressing (and not helpful at all), especially when they're unwilling to help you on your level. Sometimes they're so high you don't even know what to ask!

Those last issues (scarce documentation, poor examples and community of magicians) very often come together, especially in case of fairly young, but warmly welcomed APIs.

share|improve this answer
"Poor examples".. Yes it hinders the learning process of the API. Sometimes the API usage gets difficult when design desions are clear mismatch between the example’s purpose and the user’s goal. Also providing snippets in large number do not support for thinking about “how to put things together" –  Ashwin Jun 19 '11 at 12:30

As others have already stated, adequate documentation and good code examples can make an API easier to work with.

But here's another thing that's important:

An API must return relevant error codes.

If you're with an external API, and things aren't working, esoteric error codes can make your life miserable.

share|improve this answer
Good point. Error codes and its docs will help making good S/W modules and helps to know things better. :) –  Ashwin Jun 19 '11 at 15:37
Thankyou for reviewing my post... :) –  Ashwin Jun 19 '11 at 16:57
Actually, I'd totally disagree with this- an API must throw relevant exceptions. APIs with error codes are definitely down there on the list of bad APIs. –  DeadMG Jun 19 '11 at 18:22
@DeadMG: Should RESTful APIs throw exceptions? –  Jim G. Jun 19 '11 at 19:56
Yes. I can appreciate that when it comes to sending the error down the network that you may need to represent it as an error code, but once it reaches the machine on the other end, it should trigger an exception. The fact that internally it needs to be represented as an error code is an implementation detail. –  DeadMG Jun 20 '11 at 12:29

Definitely invisible variables.

For example, look at the D3D9 API. BeginScene/EndScene. Is the scene begun? Well, that's an invisible variable that it's hard to reason about. Why don't Microsoft just add an "IsSceneBegun" member variable and do it for you?

Another example is shaders. You set them to the device, then you render from the device- but you sure can't draw without a shader. Why not change the Draw() functions to be on the shader interface?

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.