Microsoft Releases REST API Guidelines, Says Documentation is Critical

Convergence Corner

Microsoft Releases REST API Guidelines, Says Documentation is Critical

By Erik Linask, Group Editorial Director  |  August 10, 2016

One of the big themes apparent from the first day of the recent All About the API conference  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 event keynote speaker Microsoft (News - Alert) API Architect Gareth Jones. 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 asked.

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. That includes 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 guidelinesthe release of which Jones announced during his keynote. 

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,” said 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.

**

“Everyone building APIs needs API guidelines. 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.”

– Microsoft API Architect Gareth Jones




Edited by Alicia Young