search

microsoft / code-with-engineering-playbook

This is the playbook for "code-with" customer or partner engagements
https://microsoft.github.io/code-with-engineering-playbook/
Creative Commons Attribution 4.0 International
2.23k stars 587 forks source link

Microsoft REST API Guidelines Deprecation #956

Open scgbear opened 1 year ago

scgbear commented 1 year ago

Describe the bug The Azure API Stewardship Board is currently in the process of deprecating the Microsoft REST API Guidelines. The guidelines themselves havn't had an update in 4 years and there is no clear owner of these guidelines.

They have updated the main README.md for Azure Service Teams and GraphQL services to use the their relavent REST Guidelines. with the following content:

NOTICE TO READERS
Guidance for Azure service teams
Azure service teams should use companion documents, Azure REST API Guidelines and Considerations for Service Design, when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the README in the Azure folder.

Guidance for Microsoft Graph service teams
Microsoft Graph service teams should reference the companion document, Graph REST API Guidelines when building or modifying their services.

In the process of building many of Microsoft's highest scale services, the Microsoft Graph team found the Microsoft API guidelines tremendously useful as a baseline. However, there are several areas where we need to provide more clarity on how developers should describe their APIs. The companion document, Graph REST API Guidelines is a set of amendments and clarifications for Microsoft Graph that act as further reading. Recognizing that two documents is a lot for a new API designer to absorb, our plan is to follow the approach Azure have taken and roll out guidelines for Microsoft Graph into a single consolidated document.

This playbook is currently referencing these soon to be deprecated guidelines here: https://github.com/microsoft/code-with-engineering-playbook/tree/main/docs/design/design-patterns/rest-api-design-guidance

TessFerrandez commented 1 year ago

Thank you for this comment @scgbear, sorry didn't see it until now... but when looking into it, I couldn't find the notice about deprecation... so I am unsure about what has been deprecated.

If you have the bandwidth, could you create a PR to modify/delete the outdated content

liammoat commented 7 months ago

Reference (I think): https://github.com/microsoft/api-guidelines/blob/vNext/graph/Guidelines-deprecated.md#deprecation-notice-to-readers

I'm happy to drop a PR on this if required