API development - Design considerations

Question

In my 4 years of experience,I have developed a lot of web applications. Now, the concept of programmable web getting more and more popular, new APIs are being released almost everyday. I would like to develop a java API/library for a few of these endpoints.Ex stackapps,reddit,digg etc... What I would like to know from you people is ,

• How is the API of the regular web apps differ from the API of these libraries. Or what is the difference between these two from design perspective
• What are the best API development practices.
• What are all the factors that I need to consider before designing the API

.

Please comment, if the details are not sufficient.

Answer 1

From my experience, all good API were not made to solve a generic problem, but to solve a problem for some that requires a certain abstraction. This abstraction is then evolving as the requirement and/or the underlying layer change.

So instead of finding the API that will do it all, I'd start by finding one or two good case problem were your API could help.

Answer 2

Stability

If you offer an API to your web app, it is probably because you want other people to build applications using it. If it is not stable they will hate you for forcing them to follow through your frequent changes. If this takes too long, their site might remain non-functional for a long time while they are figuring out the new way of doing things in your API.

Compactness

You want the API to be complete but compact, as in not too much to remember.

Orthogonality

Design it so there is one and only one way to change each property or trigger an action. Actions in an orthogonal API should have minimal (if ever) side effects.

Also, it's not a good practice to remove a feature from a public API once released.

Security and Authentication

Since the API is web-exposed, you will have to authenticate each request and grant appropriate access. Security common sense applies here.

Fast Responses or Break into pieces

I believe in a web environment we should have fast responses and avoid requests that will take too long to complete. If it's unavoidable then it is better to send an ACK and break the task into several pieces and subsequent calls.