add an article to explain graph top-level segments and included the rules for /external
#538
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@microsoft/graphguidelinesapprovers ping... |
OlgaPodo
added
the
Microsoft Graph
OlgaPodo
reviewed
Jul 11, 2024
| @@ -0,0 +1,15 @@ | |||
| # Graph Taxonomy | |||
|
|
|||
| Different top-level segments have different requirements and these rules MUST be followed: | |||
There was a problem hiding this comment.
- 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
I think that bringing 3P data is not equal to exposing 3P APIs on Graph therefore this sentence is not relevant.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
/adminshould be added in the future.