Software developers want a way to integrate their software with yours – and they don’t want things broken down for them. This is where an API comes in.
It is the nature of software development. Developers create software with the end user in mind. It seems pretty simple, but sometimes those users are also fellow developers. They don’t need things broken down for them. They don’t need even need the simplicity. All they want is access – a way to integrate your software with theirs. This is where an API (application programming interface) comes in.
The five steps to creating a successful API are:
1. Do Your Homework
When 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.
2. Be Consistent
One 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 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.
3. Use OAuth
Most 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.
4. Start Early
One 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.
5. Write Good Documentation