For a business whose central focus is a web application, the API is often a springboard for moving the company from just another application to a platform for developers. When an application becomes a platform, the participation of developers can move business forward. Cultivating and maintaining an easy to use, high quality API entices developers to build on your application in innovative ways. Encouraging this behaviour is mutually beneficial for both parties. New applications can take advantage of work and data from previous apps, and customers receive greater value out of applications that are capable of these interactions.
Despite these benefits, APIs are sometimes relegated to a second best effort, or an afterthought of development. While the API may not be the front-end for the majority of your customers, it’s still a valuable entry point to your business, and its maintenance should be treated with the same importance, design, and care as your main application. Choosing to invest time into the design and development of your API can make it more appealing and "friendly" for developers to use, encouraging the growth of applications built upon your API.
At Mutually Human, we work with lots of APIs, as well as with clients across the world whose businesses depend on APIs every day. We have experience with both building and consuming APIs. What follows is a checklist of good practices for making your API friendly and appealing to developers, encouraging growth and development for your platform.
Friendly APIs are consistent.
By keeping aspects of an API as consistent as possible, you decrease the amount of time and energy a developer needs to spend to learn and implement a given task.
For instance, if your application allows users to create groups and to invite users into those groups, make the API requests between them consistent. Don't request XML to create a group, and then require JSON for an invite. If your API uses REST, try to adhere to RESTful guidelines (don't use an HTTP get request to delete an object, for example). This isn't to say one method is better than another, but for choices you make in your API, apply them consistently throughout the entire API.
Friendly APIs handle changes responsibly.
Changes to your API are bound to happen. Features within your app, the data you choose to store, and the functionality provided are all subject to change, often based on the needs of your users. Don't hesitate to add these new features to your API, the more feature-filled your API is, the more useful it will be to developers building on it.
However, be mindful of your existing API and its users. Add features gracefully, so that existing API users can continue to use the API as-is without the new features, and test both of these use cases (preferably with your automated test suite).
If there are valid technical constraints that prevent this strategy from working, use versioning to maintain the existing API while still allowing developers to use the new features you’ve implemented. Breaking compatibility with your old API isn't necessarily a bad move, but it should be done only when absolutely necessary, and performed with the utmost of care.
Friendly APIs are informative.
Developers will be using your API to build applications, so providing them with as much information as you can will aid them in creating high quality experiences on top of your platform. Your platform will be judged by the quality of the applications using your API, so give anyone using it as many opportunities for success as possible.
Errors are inevitable when communicating between any two services. Be sure not only to handle errors, but also to provide as much detail as possible. A vague error such as "Email invalid" is not nearly as helpful as a specific error message like, "Email address provided is not unique. Email addresses must be unique across all customers, vendors, employees."
Documentation is an often overlooked area of APIs as well. Clean, easily navigated documentation can assist developers with your API, lowering support costs and increasing the quality and user experience of independently-created applications on your platform. While it's sometimes regarded as the least interesting part of creating an API, it's arguably one of the most important parts. Keeping the documentation available, accurate, and up-to-date will provide developers the knowledge they need to use your API effectively.
Friendly APIs are thorough.
When implementing your API, be as thorough as possible. The more complete your API is, the more likely quality applications will be built on it, and the more efficient they will be.
For example, filters and/or queries are great ways to reduce the amount of data needed in a request, but are often overlooked when implementing APIs. If you don't implement these, you've ensured that developers who need this functionality will have to resort to much less efficient methods of data retrieval, such as querying for all records and filtering them within their own application.
Another way to be thorough is to have as much coverage over your application functionality as possible. While your application might not need to expose all functionality through its API, the more you expose, the more useful that API will be for developers. At the bare minimum, your API should allow the import and export of any customer data it contains. For instance, if you’re writing a contacts app, the API should, at the bare minimum, cover creating, retrieving, updating, and deleting of contacts.
Friendly APIs are safe.
You can't ensure that applications that connect to your API will handle their security concerns well. However, careful design of entry points and permissions can set them up for success, and help protect your users in the process.
SSL
While most developers are aware of the security concerns behind session hijacking and the sending and receiving of unencrypted data, many often overlook the security around their API. One of the first steps you can take to secure your data is simple; just require any API requests to be sent over an encrypted connection (HTTPS). While this one measure alone cannot provide complete protection, it’s a good start.
A Proper Authentication Scheme
Don't allow developers to directly use the user's username / password for authentication. These are tempting in part because of their convenience. But if you allow developers to authenticate with their users’ username and password, you've guaranteed that some developers will forever be storing this information within their own applications or databases. A much better solution is non-credential authentication patterns, such as OpenID or oAuth. Reducing the use of user passwords will help protect their security, and reduce the chance of them becoming compromised.
Permissions
Implement permissions for APIs within the user area of your applications. Users are often not fully informed about what an developer will be able to access through the app's API, and be confused as to the security implementation behind them. Allowing them to control any developer's connection to their account through a permissions system enables them to have confidence when using the developer's application, as it restores control of the user's data back to the user.
Twitter partially implements this model. It uses oAuth for user authentication, and allows a user to log into Twitter and see a list of all "Apps" (API users) connected to their account, and allow/revoke access at will. One great addition would be to break down 'access' into permissions, such as "I allow App X to read my tweets, but I do not allow App X to write tweets under my name".
Conclusion
These are just some of the many things a developer can do to make their API more usable for other developers. As a regular consumer of APIs, these are the kinds of things I wish others would do more often. And while it's not always glamorous work, APIs are the foundation that platforms are built on. Tending to these needs will help your application, its platform, and business prosper.