API design

in Uncategorized

15 Design Tips for Your API

API designvia Deviant Art

Should your startup make it’s own API?

Building your own API permits access to all three layers of architecture: data, logic, and presentation, but if you don’t own your API, you are not privy to the data and logic layers. Constructing an API for your startup gives you more autonomy, and will result in faster shipping and product release. Creating your own ecosystem is strategically valuable when forming partnerships and building business. Good Maps is a great example of a solid API; it’s incorporated into countless apps and websites. Poorly designed APIs, however, can seriously undermine your business. After all, bad product equals customer loss. APIs that are too complicated, don’t solve a problem, or lack security, fall under the bad product umbrella, and we all know what that means.

It’s difficult to make changes to your API once it’s released, so you want to build the best possible API from the get-go. If you’re in a position to create an API for your product or for public use, you have plenty of decisions to make — formatting, versioning, caching, and so on. There’s plenty of opinions out there, and no one standard that will work in every case, but to help you out, we’ve gathered 16 of the best tips to guide you in making a great API:

Simplicity Wins: No matter who you’re making your API for, complexity usually spells out failure. Rather, simplicity equals massive adoption (see Google, Apple). So when you take into account the rest of this list, always keep in mind that you need to create an intuitive API to result in a great product.

Consistency: Designing intuitively means consistency, especially when it comes to calling conventions. For example, if you require a filename as the first argument in one of your functions, always do that for functions requiring a filename. Otherwise, it’s counterintuitive because you’re causing customers to memorize signatures for every function.

Clarity: Every name should reflect a function, avoid using anything that refers to your company brand (only intuitive internally). Names should tell you what the function is, and what each type contains or abstracts, and arguments should be clear — not ‘true’ or ‘false’. Instead, utilize arguments that tell you something, such as IgnoreCase. Verbs are incredibly useful in your API, as it guides users with a familiar experience towards correct usage. For example, a ‘Delete’ should delete a resource, and ‘Update’ a resource.

Clearly Define Success & Failure: Don’t force the customer to go in blind, trying to figure out where the operation went wrong. For failure, return something other than ‘null’ or ‘void’ to help them fix the error correctly. In the same vein, they should know if their operation was successful too, either by returning a ‘success’ code or establishing that a lack of error code equals success (consistency). Be helpful so your customer can debug quickly!


Detect Failures: There will be failures, so plan to detect them. Did a connection fail because of an invalid address, invalid login credentials, timeout? Detecting failures allows you to understand where your API needs help.

Documentation is Key: Documentation is a must, and it’s also one of the most difficult things to deliver. Documentation should be simple and easy to understand, and always try to avoid errors and misunderstandings in your documentation — developers do not take kindly to these mishaps. Consistency is huge when it comes to documentation, and it’s something many miss the mark on. You can help your users out and keep them up-to-date by including examples of workable code snippets in your test cases.

Authentication: For non-public APIs, you need authentication. There are many mechanisms for API authentication, but the accepted standard is to use tokens. You can use something simple like JSON Web Tokens (JWT), or something more robust like OAuth, which is used by well known APIs we use daily like Twitter’s or Netflix’s.”

Rate Limiting: With a successful API, you might have thousands of customers using your product at once, and that’s where things get dicey. Inexperienced developers create endless loops, resulting in calling your URL 1000’s of times an hour. To prevent slowing and crashes, implement rate limits (e.g. Redis, Nginx limit_req) early on. Make sure you convey rate limit info clearly to your consumers, it will help them use the API properly.

Caching: The goal of caching is to gain speed and reduce server load. You need to cache your API right away so your consumers receive snappy responses from the get go. There’s a few ways to do this including: Reverse-Proxy-Caches(Nginx,Varnish), Russian Doll Cache, and self-invalidating cache keys.

Always Version your API: There’s no reason not to, it’s free! If you’re not sure you’ll create a second version, still do it. If your product is successful, you’ll probably have to tweak your API and release a second version, and changing a published API is no good for anyone involved. Your consumers rely on the published API, and it could fail when you make changes — leaving you with anything from minor issues to major lawsuits.

Security: Don’t ever jeopardize your client’s software. Any cryptography used to protect sensitive data should be well tested and standardized within the standards used by security professionals. This is serious business, so avoid doing things like inventing your own ciphers implementing your own cryptographic algorithms — these can be easily screwed up.

Configuration flexibility: Consumers will be thankful for libraries that link to the application’s binary and offer flexibility. You can do this with code, as a file within the application’s configuration file, or in a separate configuration file.


Always Test First: Maybe this goes without saying, but testing out your API in a useful program with a UI is going to give you the best feedback to find out where your API has mistakes, inconsistencies, or unnecessary complexities. Anything that puts you in the shoes of your consumer to figure this out before shipping is a bonus(i.e. developers not on the building team, developing an API with a program).
Solve a Specific Problem: Make the solution you’re providing your customers very clear. Parse is a great example, “The Parse platform provides a complete backend solution for your mobile application…eliminate the need for writing server code or maintaining servers”. Voila, there you have it.

Try it now, Buy it Later: Consumers are hesitant to buy anything that they can’t try, especially if it’s new to the market. Make it super simple for customers to sign up and get started, and if you have a great product — they’ll be sure to buy.

Offer Great Support: Support should start from the moment your customers sign up, with well made guides and references. Back it up with an awesome team of people who know the technical ins and outs as well as how to be an effective people person. If your customers are frustrated with nowhere to turn, you can bet they’re not going to recommend your API to friends.

Building an API, a good API at least, is an enormous boost for your startup’s efficiency and growth. The most obvious benefit — autonomy over each layer of infrastructure, which will contribute to rapid release of your product. APIs are also business building blocks of their own, the API trend grows as companies increasingly piece together APIs to form specialized startups. So why not build out to different audiences? Your first attempt may not be perfect, but investing the time into making a great API could be a major pay off in the long run.