5 Steps to Creating a Successful API

By Brandon Peters
Published: May 3, 2012 | Last updated: October 2, 2012
Key Takeaways

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. In this article, I hope to highlight five steps that you can take to create a successful API.

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.

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 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 <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 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.

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.

Write Good Documentation

Nothing 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.

API Development: Keep It Simple

While it may seem that developing an API is a complicated endeavor, the idea of an API itself is not a new concept and there is a large amount of available documentation on each topic we touched upon here. Just be sure to use good practices where you can find them, and to provide a consistent, well documented interface.


Share This Article

  • Facebook
  • LinkedIn
  • Twitter

Written by Brandon Peters

Brandon Peters is a software developer atFormstack, an Indianapolis-based SaaS company. Brandon assists in developing new features and application products for the online form builder. Before Formstack, Peters worked as lead software architect at Selican Technologies, Inc., and as a computer support specialist at the Center for Computational Biology and Bioinformatics. He specializes in Web development, computer support, data administration, unit testing, and more.

Related Articles

Go back to top