‹/› Devsworld News

Devsworld Home

Microsoft Releases REST API Guidelines, Says Documentation is Critical to Success

By Erik Linask
July 20, 2016

One of the big themes apparent from the first day of the All About the API conference this week is that, while there is little doubt APIs will dominate the business landscape going forward, thanks to the incredible potential they have for creating new business and revenue opportunities, the key lies in a well-designed API strategy.

When it comes to writing new APIs, success rides on writing the right APIs – not just any APIs – according to Microsoft API Architect Gareth Jones, speaking on the keynote stage in Las Vegas.  Before undertaking any development efforts, it’s critical to understand what your objective is and, more importantly, how your efforts will benefit your customers and users.  “Would you build an application without understanding your users’ goals?” he asks.

This is something the tech market clearly understands, given the countless times I’ve been told that new products and services or enhancements to existing ones have been defined by user demand.

To that end, Jones said in his talk, “Ask not what your product does; ask what your integrations will do for your customers, and use that [to] drive your API strategy.”

For instance, the mobile movement, heavily influenced by developments around cloud computing, has motivated many a business to move from a local to a mobile development strategy, including Microsoft, which sent its Office suite on a path from being a desktop application to a full-featured, cloud-based and API-powered business service.  Given the 340 million mobile downloads to date, it was a well-designed strategy.

There are several factors that contribute to the success of API strategies once a path has been determined based on value to users, not the least of which is proper documentation – and then sharing that documentation to help developers effectively leverage them.  This definition is a key part of creating a consistent user experience, and one that has to be relentlessly pushed to the user community, according to Jones.

Practicing its own theory, Microsoft built on its experiences from having created one of the largest collections of Web services in the world, and from the mountains of feedback it has received from users of those products and related APIs, to construct its REST API guidelines, the release of which Jones announced during his keynote.  You may find the guidelines here.

Not long ago, development was purely the realm of developers, but the rise of APIs has transformed development into a domain occupied by not only developers, but also IT professionals, in general, as well as what Jones calls “citizen integrators.”

To ensure this new constituency of developer-users will be successful, it’s critical to develop and promote proper guidelines.

“Everyone building APIs needs API guidelines,” says Jones.  “If you have guidelines, make sure you are using them and evangelizing them – and if you are mostly an API consumer, demand the use of guidelines from your suppliers.”

APIs are here to stay, but the difference between successful and ineffective API ventures will be defined by development and distribution strategy, including the all-important documentation.  Even business application leaders like Microsoft are following this process – you should too.

Edited by Alicia Young

Group Editorial Director

Related Articles

Telecom API Market Set for Big Gains

By: Steve Anderson    3/24/2017

A rapidly increasing need for APIs and similar measures is expected to drive big gains in this market through 2021.

Read More

Flowroute to Discuss Common API Mistakes at All About the API

By: Alicia Young    2/8/2017

Doug Waller of Flowroute will be taking part in a panel at the All About The API event, collocated with ITEXPO, to discuss common mistakes that occur …

Read More

Wear Your Lifestyle with Google's Awareness API

By: Alicia Young    2/8/2017

Google has teamed up with H&M's digital fashion house Ivyrevel to use its Awareness API in a unique way. The duo wants to digitally design customized …

Read More

10 Trends that Will Impact Open-Source Technology

By: Special Guest    2/8/2017

Open source has become an integral piece of every developer's arsenal. The power of the community, the wisdom of many, and the ability to hook into va…

Read More

What the Google Hangouts API Shutdown Means

By: Special Guest    2/6/2017

Google's in an interesting place with Hangouts and chat with both the enterprise and the consumer. One thing is clear - what it's doing with Hangouts …

Read More