15 Design Tips for Your Startup’s API
On July 6, 2015 by Eric Norton
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. Construction of 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. Take, for example, the well-designed GoogleMaps, which is incorporated into countless apps and websites. Poorly-designed APIs, however, can seriously undermine your business. After all, bad product quality 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 be sure 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 are plenty of opinions out there, and no one standard will work in every case, but to help you out, we’ve gathered…
15 of the best tips to guide you in making a great API:
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 abstract, 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, in HTTP Delete = remove from 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. Including examples of workable code snippets in your test cases will keep your API up-to-date and help your customers.
Authentication: For non-public APIs, you need an authentication. It’s pretty simple on the client side, username and password is entered by the consumer and HTTP Basic authentication is implemented in every HTTP client. On the server side, Rails is pretty darn simple to implement, and you can use private access tokens to protect passwords from external services.
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 incorporate it into their API clients. There’s a few ways to do this including: Reverse-Proxy-Caches, Russian Doll Cache, and self-invalidating cache keys, just monitor the effectivity for anything you cache.
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 teak 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 sensitive data or cryptography should be well tested and standardized with the use security professionals. This is serious business, so avoid doing things like inventing your own ciphers implementing your own crypto-primitives — 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 complexities. Anything that puts you in the shoes of your consumer (i.e. developers not on the building team, developing an API with a program) to figure this out before shipping is a bonus.
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 majorly pay off in the long run.
Tags: api, design, software development
Originally published at blog.jixee.me on July 6, 2015.
