Announcing Updates to the REST API Experience

This post was written by Jessie Huang, Program Manager on the docs.microsoft.com team.

Today, we are happy to announce the release of two key improvements to the REST experience on docs.microsoft.com:

  • The preview version of the REST API Browser--an easy way to search and discover REST APIs developed by Microsoft.
  • REST Try It--an interactive experience allowing you to try REST APIs directly in your favorite web browser.

Discover REST APIs in One Location

If you are already familiar with any of our existing API Browser experiences, such as that for .NET, PowerShell, Python or JavaScript, you will feel right at home with this new release - it allows you to quickly get documentation for a wide variety of REST APIs without having to rely on a less focused search experience. The API Browser is all about getting you on your way quickly by finding the right API in seconds.

Previously, if you wanted to find specific REST API documentation on docs.microsoft.com, you may have had to look for it through our site-wide search, or use any of the navigation components on content pages, such as the table of contents. That may be time-consuming, especially in situations when you know exactly what you are looking for. We wanted to make that easier.

Starting today, you can discover Microsoft REST APIs in a much more efficient manner, from one centralized location - https://docs.microsoft.com/rest/api. Simply select a service from the dropdown to find all available service APIs:

Discover REST APIs by selecting products

Need to save a click? For some of the most frequently used APIs, you can always count on Quick Filters - clicking on one of them will instantly bring up the comprehensive set of APIs for a given service, for its latest release:

Discover REST APIs via in-page quick filter

We designed the search experience in a way that allows you to find the necessary API information whether you know the exact keywords or not - or even if you don't know the service it's in! By default, we will search across all APIs documented on docs.microsoft.com. Only when a service is selected, the search will happen within the scope of that service.

Searching REST APIs by a single keyword

Need to search for multiple keywords at once? You can do that too!

Searching REST APIs by multiple keywords

Try Azure REST APIs in Your Browser

Found an Azure API of interest, but don't know if it's quite what you need to help you build out your scenario? Worry not, because starting today you can try Azure REST APIs directly in your browser, on docs.microsoft.com!

All you need to do is press the green Try It button:

REST Try It - Launching the experience

Once you select Try It for a REST API, you will be taken to a focused view, allowing you to experiment with different parameter values or request body. You can just as easily change the article context by using the Contents hamburger menu in the top left corner of the page:

REST Try It - Changing the article context

We Want Your Feedback

There are many improvements we plan on implementing in the near-term, so this experience is by no means final, for example we will enable Try it not only for Azure REST APIs. We want you to tell us how we can make our REST experience better - just open a new issue, and we will get back to you as soon as possible.

You can also follow our Twitter account for latest updates and notifications!

Dreaming of making the world better for developers? Join our team!