[dehora]

It's great to see Microsoft release these guidelines. It's good work, a broad document with a lot of interesting topics covered. You can always debate the details (the pagination discussion here is very interesting), but having seen first hand at Zalando how much dedication and effort goes into API guidelines to support a large number of service teams, plus releasing them into the public, it's no small feat and they deserve credit for doing this.

There's naturally been some discussion around REST/HTTP APIs and design styles. One of the things we've tried to do with the Zalando guidelines (https://zalando.github.io/restful-api-guidelines) is go into more detail on using HTTP and JSON, and how REST properties are used. Zalando, like everyone else, has had to think through versioning and compatibility, so it was interesting to read what Microsoft do here. The Zalando guidelines take a different approach, using media types for versioning, document just one set of compatibility rules, plus a deprecation model, and it's working very well in practice so far (http://zalando.github.io/restful-api-guidelines/compatibilit...).

Btw, in case anyone from Microsoft working on the guidelines is reading and ever wanted to swap guideline notes or ideas, that would be awesome. And once again, great job releasing the doc :)