Today’s consumer is over-saturated with mobile and web applications. Even a single brand may have several apps in market, each competing for the consumer’s attention and fragmenting the brand experience.
Having a successful digital strategy requires a long-term vision. At the core, this means building and supporting multiple platforms with continuity. An API (Application Programming Interface) is an important method for defining the interactions of a particular product (i.e. what it does / how it can be used) and allowing those interactions to be easily integrated into other platforms. APIs extend the reach of your company.
Providing an easy to use API can pay huge dividends. It can drive adoption by making your services ubiquitous (users interact with your brand even within apps that you do not “own”) and by reinforcing the value of your services (investment in user experience translates as an investment in the user). APIs enable Software as a Service (SaaS) models and are the very foundation of The Internet of Things (IoT); their role is only becoming increasingly critical.
A successful API implementation has a long lifespan. It can help drive value to the business and support the business objectives for many years. When done right, it should expose the company’s most valuable assets.
What are some thoughts to keep in mind when building an API?
Make the API approachable:
- It should be easily adoptable by other apps and websites
- It should be well-documented so that developers can easily work with it
Much like developing a website or app, the development of a successful API should follow a process. The key aspect is its long life potential. Proper planning will ensure your API thrives with you.
It’s equally important to plan changes and updates carefully once people start using your API. Changes you make can have significant impact to the external applications and services that rely on you. Think about how many times Facebook API updates forced existing applications to be rethought or rebuilt entirely because a key function was no longer available.
Make users want to use the API:
This is often the hard part, but at minimum the API should be simple and solve a single problem at a time. It must extend useful components that users want and can’t get by without. Let the users of the API worry about solving “big” problems. The API itself is not about solving problems, it’s about providing building blocks for others.
How to get started building APIs
API process, when planned properly, should be similar to application design process.
- Gather the Use Cases
- Identify which core components and competencies of your organization can drive value to you and can offer value to others.
- Carefully break down how each component can be used. What it will offer and how?
- Prepare specifications
The specification should break down precisely which APIs are being offered and how they are to be used. For example. You may have a database of sales contacts that you’d like to expose via an API. In the specifications you must be explicit about the details of which functions you’ll provide (for example, login, read-contacts, add-contacts, update-contacts, delete-contacts, link-contacts) and also how they’ll be used.
- Prototype often
Before deciding on what will be supported, it’s important to run in-house trials of the APIs and work out any inconsistencies and use cases. Once the API is out there and available to customers, it’s really hard to change it and change will take a long time. It’s imperative to give yourself enough time to test the API out.
- Don’t impose too many constraints (and then remember, you can’t please everybody)
Do one thing and do it well. That thing should be easy to explain and understand. There will be things you just won’t do and that’s fine. You must identify the key components that will drive value to your platform and focus on those. The APIs should be minimalist, the less they can contain, the better. They should also be agnostic so as to be consumable from any device, OS, browser.
- Be clear and specific
Follow proper abstraction principles and hide implementation details. Use intuitive names. As a guide, certain elements of your design should be easy to memorize. All functionality and specifications should also be clearly documented. Ideally, documentation should be made available with test functions. A great framework for helping you document your APIs is Swagger.
Advanced tips for building proper APIs
Since web is the most dominant platform, focus your API first on leveraging the web. More specifically, in order to increase adaptability most APIs designed today should support the HTTP protocol, even if they’re designed for internal corporate use.
- Focus on REST
RESTful APIs offer resources. A resource is an object with data and relationships to other objects. RESTful APIs should be named by using nouns and not verbs. The HTTP actions of POST/GET/PUT/DELETE should map to Create/Read/Update/Delete accordingly. To learn more about the specifics of REST check out this tutorial.
- Secure them properly
Don’t reinvent the wheel on security. Use HTTP security (SSL) and leverage well-adopted and tested standards.
- Versioning
Your API will change and evolve. In order to support different versions the version number should be included with each call in the URL or the header.
- Focus on JSON and ditch XML
Today JSON support is everywhere and XML is fading away due to its complexity and verbosity. It’s time to take the leap of faith and leave XML behind.
- Maintain no state
A RESTful API is a stateless API. This means that the API calls should have no cookies or sessions. It implies that each request should be authenticated. The most common way of achieving that is with bearer tokens.
- Handle Errors
Provide useful error messages. Use top-level error code for validation and provide further detail in your JSON.
Summary
In order to attract customers to your platform (read also as product, service, brand asset), the platform should provide easy to use APIs that help extend its reach to others. The APIs should be carefully crafted and follow best practices described above.
If you’re building APIs, we’d love to hear your thoughts, lessons learned and suggestions below.
Originally published at Medium.com on June 14, 2014
If you have an unmissable opportunity – schedule a free consultation with one of our founders.
