Do Your HomeworkWhen it comes to software development, none of us wants to reinvent the wheel. At this point, almost all large Web companies have APIs for their software products. Study these APIs and try to pick up on the different design decisions that went into creating them.
There are many different technologies out there, but most of the APIs you will see are going to be using either a RESTful interface, or SOAP. If you’re on the fence as to which API interface you are going to use, I would suggest going with a RESTful approach using the HTTP protocol. It’s simpler than SOAP, it's currently more popular, and it will be easier to get started with when using a Web-based software product.
Be ConsistentOne of the things that developers appreciate the most is consistency. This includes, among other things, addressability, input arguments, output formats and error handling.
When using a RESTful approach, there are many different URI naming schemes. Each one has its supporters, so just pick one and stick with it. The same goes with input and output structure. Most APIs support using XML and JSON as input and output formats. I would suggest supporting both, but choosing a default format.
For input, your input requirements should be named consistently and should make sense in the context of the API call you are making. For output, make sure that you are using common data structure layouts. If you are wrapping the output of one API call in a <response> XML tag, consider doing that with your other calls.
It is a common practice to include some sort of status flag in the output data you send back to the client. When using a RESTful API approach, this should be done using HTTP status codes. For instance, if you just processed a PUT request on an existing data object, the HTTP status code you include in your response will vary depending on the outcome of the request.
Instead of an arbitrary flag that indicates the status of the call, a standard "200 OK" status code can be used to signify that the request was successful, while a "400 Bad Request" status code could be used to signify that the request was malformed. There are quite a few HTTP status codes that can be used in different situations.
Use OAuthMost software products will involve some sort of user authentication in order to access protected resources for that user. When it comes to APIs, having the client collect the user credentials to send to your server is a bad practice. This is where OAuth comes in.
OAuth provides many benefits over third-party username/password authentication. Above all, the client never has access to the user’s credentials. The user is redirected to your server when he or she logs in. After the user logs in to your site, he or she is redirected back to the client where the client will receive an access token to use in future requests to protected resources.
Another important benefit of using OAuth is the user’s ability to cancel client access at any time. If the user decides that, for whatever reason, they no longer want the client to be able to access protected resources on their behalf, they simply go to an interface you have created and cancel the client’s access.
Start EarlyOne of the most important things you can do to make your API a success is to start early. When you write that function to create some entry in your database, go ahead and take the extra time and write an API interface for it.
Write Good DocumentationNothing kills an API faster than not having good documentation. While some developers can take a poorly documented API and figure out how it's supposed to work, most won’t want to.
You should document every API call that you have available and categorize your API calls by the type of data they act upon. Along with documenting the endpoints for the API calls themselves, you should systematically define the required and optional input arguments as well as the output data structures. Input arguments should list a default value if there is one, and also indicate the expected data format such as a number or string. Lastly, every API call should have a list of error conditions and status codes.
To round out your documentation, be sure to include one or two examples for common input and output scenarios for each API call.