Win with APIs by keeping it simple

Whether you’re making consumer products or business software, complexity usually means failure.

Less is more. We all know examples where this philosophy has resulted in products that are incredibly easy to use and, as a result, extremely successful. Apple is renowned for its laser focus on design, stripping away any excess and refining what’s left again and again. Google Search is another famous example of simplicity leading to massive adoption.

Can the “winning through simplicity” approach apply to APIs too? Are there steps we can take when designing, building, and operating APIs that will keep APIs simple and increase their chance of success?
Indeed there are.

Make it simple to understand

You don’t need to read a manual to figure out how to use an iPhone, and you shouldn’t need to spend days figuring out how an API works before you get started.

Whether you consider Facebook life-changing or irritating, its API is mostly intuitive and simple to use. Once you get beyond authentication (the hardest part), the rest is trivial.

Typing https://graph.facebook.com/534822875 into the browser returns information about the user with the ID 534822875. This happens to be me. I get back a snippet of JSON text that looks like this:

{   "id": "534822875",   "location": {       "id": "114952118516947",       "name": "San Francisco, California"   }}

Facebook built a shortcut into its API: using /me to represent the user currently signed in. I could have typed in https://graph.facebook.com/me and received the same results as above.

The rest of the API can be navigated with a quick glance at Facebook’s API docs. In fact, I can almost guess the capabilities of the API and the names of the functions based on my knowledge of the Facebook application itself: friends, photos, likes.
For example, https://graph.facebook.com/me/likes returns a list of everything I ever liked on Facebook.

{
   "data": [
       {
           "category": "Media/news/publishing",
           "name": "The Guardian",
           "created_time": "2014-08-01T01:32:17+0000",
           "id": "10513336322"
       },
       {
           "category": "Movie",
           "name": "The Lives of Others Movie",
           "created_time": "2014-07-31T15:47:14+0000",
           "id": "586512998126448"
       }
   ],...
}

The API is intuitive and you can almost guess the names of the resources available within it.
Guess what I would type to get the list of my photos? Bingo: https://graph.facebook.com/me/photos
Here’s another example. Want to get those same photos from Flickr? Try:

https://api.flickr.com/services/rest/?method=flickr.people.getPhotos

People will give dozens of technical reasons why they don’t like the Flickr API: It’s not RESTful and so forth. But at the most basic level, the problem is it’s not simple. It’s not intuitive or memorable or easy to understand. As a developer, I’ll always have to go back to the documentation. That by itself will hinder adoption.

By contrast, the Facebook API is simple to understand at a glance. It’s easy to get started and get going. That’s why more than 200,000 developers have used it to create more than 1 million apps.

Make it simple to use

Following on from the “make it simple to understand” principle is taking a RESTful approach to modeling APIs. This means using HTTP resources and actions the same way a browser interacts with the Web. This will give you the benefit of modeling your API after real-life items and relationships in your business. How you talk about your API will map closely to how your employees, customers, and users talk about your business.

Take a look at the following RESTful API URLs, which allow you to retrieve accounts or get a specific bank account.

# list all accounts
GET /accounts

# show a specific account
GET /accounts/{account-number}

The following returns an invoice for a specific account. It’s modeled on a real-life example.

GET /accounts/6242525/balance

You can imagine a customer on the phone saying, “My bank account number is 6242525. Could you tell me my balance?”

Taking this approach means you end up with a common and meaningful language throughout your API that maps to your business and makes it easy for developers to understand. Another benefit of following RESTful practices is that many API calls can be easily invoked via your browser address bar, so trying them out is relatively simple.

Simple data formats

JSON is becoming the de facto data exchange format for a very good reason. Developers are tired of working with verbose formats like XML. They no longer want to write custom parsers and prefer a lightweight option that's easy on the eye. JSON solves many of these problems. In addition, if you -- like many API users -- are working in JavaScript, it’s easy to bring JSON into your code.

JSON simply maps values to keys. Looking back at the example earlier, you can see that the name of the item I liked was The Guardian newspaper, and the point in time when I said I liked it was 2014-08-01.

{   "category": "Media/news/publishing",   "name": "The Guardian",   "created_time": "2014-08-01T01:32:17+0000",   "id": "10513336322"}

Navigating your API

By providing pagination links as URLs, it's really easy to navigate an API, which is especially important when dealing with large sets of data. Instead of requiring users to figure out where to go next by manually constructing URLs, your API can tell them. The following is a good example from Facebook’s Open Graph API, in which all responses return a “paging” attribute that tells users where to go to get the previous or next set of data. It’s simple, and it has the added value that a bot or crawler could navigate its way around your API.

{    "paging": {
       "previous": "https://graph.facebook.com/me/albums?limit=5&before=NITQw",
       "next": "https://graph.facebook.com/me/albums?limit=5&after=MAwDE"
   }
}

Flexible usage

Giving users control over how the API operates is a powerful move. There are many ways to do this, including the ability to sort using various rules, searching, and filtering. Field filtering is the ability to specify which fields should be returned in the response data. This can be especially useful in cases where there are bandwidth or performance issues or where a user cares about only a small subset of the API response data. Another benefit of filtering is that it limits the need for the API creator to have “different flavors” of the API because users can tell you what they care about.

https://graph.facebook.com/me/likes?fields=category,name
The API call above would tell the API to only return the fields “category” and “name” in the response.

{
   "category": "Media/news/publishing",
   "name": "The Guardian",
}

Make it simple to maintain

Every API needs to support versioning for backward compatibility. It should also give users a way to bind themselves to a specific version if necessary. The easiest way to do this is to implement a version number into a base URI and to support the latest API version under a versionless base URI. Doing both gives API client developers the choice whether to lock themselves into a specific version of the API or always work with the latest one available.

# versioning
/api/v1.0/accounts/12345
/api/v1.1/accounts/12345
/api/v2.0/accounts/12345

# alias no-version to the latest version

Companies need to be careful about changing the rules around the use of their APIs. Changes need to be vetted and carefully communicated to prevent developer revolts.

SSL

Security is critical. Provide access to your APIs over a secure HTTPS connection using SSL. This will encrypt and verify the integrity of the traffic between your user and the server, as well as prevent man-in-the-middle attacks. It’s easy to set up. Don’t even make your APIs available over an unsecured HTTP connection.

Make it simple to operate

When you get to an operational API with hundreds or thousands of users, you will need to consider a whole suite of advanced features.

Access control

You will need to provide developers with keys to access your API. Hackers may try to break in, and you will want to limit API traffic by user, to prevent developers from crashing your API -- intentionally or otherwise.

Monitoring

You will need to know when your API becomes unavailable and must be restarted. You will also need to know how your API is being used: by whom, where, and when.

Integrations

You may need to provide your users with analytics and reports on how they are using your API, as well as how often. You may need to integrate a billing system to charge for use of the API.

Some of these features are not easy to build. In fact, adding them is probably one of the more complicated aspects of the API development lifecycle. Once again, the key is to keep it simple. Don’t attempt to roll your own solution. Instead, use an off-the-shelf API solution to manage your APIs. Direct your energy into the business aspect of the APIs and what they can do to differentiate you from your competitors.

APIs that are simple and easy to use are much more likely to be adopted internally, making your architecture and business more flexible. They’re also more likely to be adopted by outside developers, potentially opening up new channels of revenue. Creating a successful API product suite can transform your business, drive revenues, and unleash innovation. But remember to keep it simple.

Read More News :- Techies | Update