add an article to explain graph top-level segments and included the rules for `/external` by corranrogue9 · Pull Request #538 · microsoft/api-guidelines
| @@ -0,0 +1,15 @@ | |||
| # Graph Taxonomy | |||
|
|
|||
| Different top-level segments have different requirements and these rules MUST be followed: | |||
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- I appreciate your initiative in raising this vital issue!
- We should include guidelines for creating top-level categories, second-level segments, and potentially other navigation paths if we develop this article.
- The rules for the 'external' node need to be discussed at the API council.
|
|
||
| * `/external` | ||
|
|
||
| * The `/external` top-level segment is used to expose data that is provided by third-party services. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we need to conder inbound and outbound flow of data.
| Doing this allows clients to have their data conveniently in a single API surface, while also maintaining consistency across the Microsoft Graph APIs and the third-party APIs. | ||
| * In addition to the first-party, scenario-based APIs, additional APIs should be released under the `/external` top-level segment. | ||
| The APIs under `/external` MUST not expose any data that is provided by Microsoft. | ||
| Any data that is available under `/external` MUST be data that could be retrieved directly from the third-party service; these APIs are only being added to Graph for convenience and interoperability. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Currently we have connectors API under /external, connectors bring data for use in different M365 experiences, I'm not sure that this use case is considered as interoperability, because for search data are indexed unique way.
| * In addition to the first-party, scenario-based APIs, additional APIs should be released under the `/external` top-level segment. | ||
| The APIs under `/external` MUST not expose any data that is provided by Microsoft. | ||
| Any data that is available under `/external` MUST be data that could be retrieved directly from the third-party service; these APIs are only being added to Graph for convenience and interoperability. | ||
| * Microsoft Graph is not intended to be a single-pane-of-glass for all third-party APIs. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that bringing 3P data is not equal to exposing 3P APIs on Graph therefore this sentence is not relevant.