The world is marching toward a more connected and intricate world than ever before. The binding agent of web applications, services and systems — the API — is becoming more commonplace and widely used. As API ubiquity increases, developing APIs with both the end user experience (UX) and the developer experience (DX) in mind is now more important than ever.

Within such a progressive economy, there are many important development strategies to consider. In this piece, we’ll offer up five API development tips that, if implemented correctly, will result in a “killer” API, turning your program into a platform for explosive growth.

1: Develop With a Long-Term Mindset

When discussing the development, implementation, and lifespan of the average API, one can broadly separate development approaches into two classes — develop for now and develop for later.

Develop for Now

The most common development process is the “develop for now” approach. These developers are creating an API for immediate use, focusing entirely on integrating existing feature sets and supporting specific sets of queries. These APIs are often well documented, built with the concept of “this is what we need, now build what we need.” Because of this mindset, they are made specifically for their design.

The downside of this approach, however, is that they are only robust at what they are designed for, and nothing more. Designing for the immediate needs and requirements of a service or system is all well and good, but it does little for long term support. Think of the old adage — feed a man a fish, and he eats for a day, but teach a man to fish, and he shall eat for a lifetime. Strict design for current needs inhibits potenital growth, ignoring how robust and diverse an API can truly be.

Develop for Later

In contrast to the previous approach, the “develop for later” approach hinges on long-term support. When applying this development approach, you don’t only consider “what does my API need to support right now?”, but also “what does it need to support in the future?”. We’re not suggesting that an image-hosting API should support audio — but if you have an API concept, consider various architectures (for instance, REST vs. SOAP vs. Thrift), methodologies, and security systems, always keeping in mind the future demands of a possibly larger, more demanding user base.

While this drives up the initial time and cost of development, the benefits of this approach far outstrip the negatives. For one, considering the future needs of your consumer base transforms your API into a marketable product, increasing your potential ROI. This benefit carries over to implementation as well — understanding and increasing the value and consumption demographics of your API is key to successful implementation.

2: Be Consistent, and Be Vigilant!

Studies from all over the world have shown that humans thrive on consistency through patterns. Pattern recognition makes sense of an otherwise chaotic world. API design is no different.

Deciding how your API will handle calls, how you will document the API functionalities, and the limitations and scopes of the various accounts that will tie into your API are all crucial factors to consider. What is more important, however, is to make sure you vigilantly maintain consistency. If your API uses calls that don’t run in the same environments, bug hunting becomes a chore. If your documentation is inconsistent with actual functionatliy, you risk confusing and segmenting your userbase.

Resolve these issues by simply staying consistent. If you have a methodology to refer to outside sources, use this methodology on every reference. If you cover a request by another multipart request, make sure there’s no needless redundancy. Check your documentation and calls as if you were a user — are they clear and concise? Are they consistent? Stay vigilant throughout development, and constantly check for these common issues.

With documentation, brevit and clarity is the golden rule. According to an MSDN article titled “A Coder’s Guide to Writing API Documentation”, documentation should be extensive but concise, with examples of more complicated calls and explanations of simplistic systems presented. A great example of this type of documentation is that of the Bit.ly API. In their documentation page for Data Streams, example code, usage scenarios, and plain English explanations occupy the same space — the text is concise, clear, and explanative, without being overly verbose.

There’s a lot that goes into designing APIs for humans, but for the purpose of this section, simply remember this Alton Brown axiom — organization will set you free.

3: Allow for Manipulation of Data

Data is only as valuable as it is understandable. Consider the following:

EnCt2089a7215d570f2426d9633d289c37f263e282808089a7215d570f2426d9633d2qH+ZBEm7xgM

VXSxVTlUQy3wnD93BcePrTE4OddWGWxESztnRypqnJ7di9y7VfVv4Cb05IwEmS

If you were to receive this data, what would you do with it? This is a chunk of encrypted text — one that was encoded using a 64 bit key. It would take well over a century for a supercomputer to crack this small amount of text. In its present format, this data is useless — there’s no way to take this encrypted string and utilize it in any meaningful way. If we decrypt it, though:

Eggs, almond milk, flour, baking soda, chocolate chips, vanilla

We find it to be a very basic ingredient list for gluten-free chocolate chip cookies. Until we knew what the data was, the data was functionally useless. So to is data provided by your API functionally useless unless it is presented in a useable format.

When users receive data from your API, consider the methodology of how it’s delivered. Delineate data by type, and allow sorting within certain limitations. In our above example, even the decoded plaintext result could be improved. If we allow for sorting the text by name, or by whether we have those ingredients or not, or even by price when checked with local grocers, we can make a powerful, dynamic service that allows for far more usefulness of API data — a common requirement amongst many developers.

Take for example an invoice and payment API tied directly into a corporate account. Let’s assume that a GET /invoices request returns data which is functionally useless, offering no ability to sort. The API user has to manually sift through much information to find what they are looking for.

Now, assume the same API is designed to allow for data manipulation. Instead of simply returning all invoices, the API allows for more specific calls, such as “GET /invoices?isPaidInFull=0”. Such a call returns a list of invoices that have yet to be paid in full, allowing the user to quickly assess the health of their client’s account and the total amount of outstanding invoices. This makes for a far more useful interface.

4: Effectively Validate and Report

The Inferno section of Dante Alighieri’s 14th-century epic the Divine Comedy describes concentric circles of hell, along with the sins of those who occupy them and their punishments. If Dante had written his epic in the 21st century and had been an API developer, he would have reserved a special circle for developers who do not validate their data and return actual error messages, consigning them to an eternity of “something went wrong” errors.

Returning useless errors that state the obvious (something went wrong), the useless (ERROR), or the downright confusing (error code:9442394) is a losing proposition — if your users can’t find out what went wrong during basic errors, they’ll stop using the API entirely. Similarly, failing to return a valid JSON, and refusing to effectively document what error codes actually mean can make a potential API development partner second-guess integration with your services, further killing potential user base growth.

The solution is simple — make sure all error returns are understandable by the “you” of the past. When you first started coding, consider the errors that gave you the most headaches. Was it “error: resource not found”? Of course not, that was clear and concise. The errors that gave you trouble were those with strange formatting like “error10002928”, lacking any documentation or references. Keep your error codes simple and well documented, and validate data with error codes providing context for why a number or field has been rejected.

Effective reporting has the added benefit of opening verbose communication between advanced users and the API operators through feedback channels, which in time will decrease both the response time to system errors and the frequency of such errors.

For a great example of both consistency and of error validation, look no further than the Twitter API’s error code documentation. Not only are the codes represented in an intelligent way (i.e., if an error is thrown due to lack of authorization, the error text simply states “Unauthorized”, paired along with a numerical marker), they are clearly laid out and defined in a searchable, manageable table.

5: Support Uptime and Redundancy

It doesn’t matter how good your API is — it might be the messiah of APIs — but if a developer user can’t access it, the API is useless by definition. You could have manipulatable data, future-proof support of innovative technologies, and clear, concise documentation, but if you can’t routinely access the service with little interruption, you’re creating a culture of failure and mistrust amongst your users, who expect near 100% uptime.

Uptime is our fifth and final tip as it is a wonderful metric by which we can holistically judge an API. It represents everything working in concert — if a single element of an API is poorly managed, uptime will likely be influenced. At the time of this writing, Bit.ly reports 100% uptime over the past 24 hours, with a yearly uptime rating of 99.9%. Likewise, the Twitter API reports 100% uptime with an average uptime of 99.9%. The proof, as they say, is in the pudding (or in this case, the uptime).

The only leniency given here is during server maintenance or temporary scheduled downtime — this is expected to surround major updates and upgrades. But when an average user only has access to your server 80% of the time, or can only call a resource 75% of the time, you are creating a poor user experience that reflects poorly on the current API, its future iterations, and the developer behind it. Uptime is key — and could mean the difference between adoration and disdain.

Conclusion

Considering the development of your API is a serious endeavor. The choices made now will impact your future success in a big way. While these solutions can be implemented after the fact, it is far easier to implement them at the start of the development cycle. Not only will this deliver a more completely integrated feature set, it will also give you a product with simpler end-documentation and user experience.

These five design concepts may be simple, but the implications of their applications are deceptively huge — implementing them can lead to explosive growth, high user adoption, and long-term use statistics.