Microsoft REST API Guidelines

400 views
Skip to first unread message

Chris Mullins

unread,
Jul 19, 2016, 2:14:42 PM7/19/16
to API Craft
A group of us from across Microsoft spent much of 2015 writing the "Microsoft REST API Guidelines" for internal use. At the end of 2015 we decided this would be more useful if the doc was open to the public and could help generate and frame API design discussions.  Today, I'm happy to say, they are published!

The Github link is:

These are internal API guidelines that we're trying to follow and represent best practices from across the company. The goal with the doc is to try to make our external API surface less fragmented and more consistent. 

The Office team has written a nice blog post about this:

These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners.  We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.

Our hope in publishing these guidelines to the greater API community is twofold:

    • First, that we will further stimulate feedback on our APIs and our approach to building them – only through such feedback can we build products that match the evolving needs of our customers.
    • Second, as we have benefitted from others in the API design community who have shared their guidelines, we want to contribute back. We believe that organizations of almost any size building APIs can benefit from having their own design guidelines.  Many companies and even organizations such as the Whitehouse have already published their design guidelines and it’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.

 

We recognize that in API design, there are multiple correct ways to do things (ex: snake-case vs. train_case vs. UpperPascalCase vs. …) and we are sharing these design guidelines as what we have settled-upon after much debate among Microsoft colleagues.  We expect that these guidelines will evolve over time and that your feedback will play a part in that evolution. 


[...] 

Cheers,
Chris

Eric Stein

unread,
Jul 19, 2016, 2:33:15 PM7/19/16
to API Craft
I haven't gotten very far, but 3.1 refers to RFC 2616, which was made obsolete by RFC 7230 - 7235.

Eric

Doug Orleans

unread,
Jul 19, 2016, 2:53:46 PM7/19/16
to api-...@googlegroups.com
While we're nitpicking, you got snake_case and train-case backwards. :)


--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

Rob Dolin

unread,
Jul 19, 2016, 4:13:27 PM7/19/16
to API Craft
Thanks Eric.  We have an issue tracking this: https://github.com/Microsoft/api-guidelines/issues/6  Would welcome your advice on if we should reference one or more of the RFCs in this series. 

Andrew B

unread,
Jul 19, 2016, 5:43:34 PM7/19/16
to API Craft
What an impressive document - there must have been some blood sweat and tears behind it I'm sure.

There's some discussion over on Hacker News about it too: https://news.ycombinator.com/item?id=12122828

Chris Mullins

unread,
Jul 20, 2016, 12:20:46 AM7/20/16
to API Craft
Thanks Andrew. 

Writing it was one of the most fun things I've ever done. Spending that much time with some of the best engineers in the world is time well spent - I learned quite a bit, got a chance to see what teams like XBox, Azure, OneDrive, Bing, and Exchange all do for their best practices, and then was able to lock everyone in a room until agreement was reached. For example, during debates over which HTTP Verbs should be idempotent, I could just ask Henrik - the man who invented them. Truth be told, only versioning was our major issue, and for (upon analysis) pretty good reasons. 

That I personally have also been involved in designing, delivering, and operating API's for AWS gives me an interesting perspective. :) 

Cheers,
Chris

Chris Mullins

unread,
Jul 20, 2016, 10:01:16 PM7/20/16
to API Craft
It's a bit more work than just section 3.1, but is worth doing. Someone is working on it now

Cheers,
Chris


On Tuesday, July 19, 2016 at 11:33:15 AM UTC-7, Eric Stein wrote:
Reply all
Reply to author
Forward
0 new messages