Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add an article to explain graph top-level segments and included the rules for /external #538

Open
wants to merge 4 commits into
base: vNext
Choose a base branch
from
Open

add an article to explain graph top-level segments and included the rules for /external #538

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
15abc28
Create external-top-level-segment.md
corranrogue9 Apr 4, 2024
4d64fb0
Create graph-taxonomy.md
corranrogue9 Apr 8, 2024
49677e0
Update graph-taxonomy.md
corranrogue9 Apr 8, 2024
155de25
Delete graph/patterns/external-top-level-segment.md
corranrogue9 Apr 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions graph/articles/graph-taxonomy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Graph Taxonomy

Different top-level segments have different requirements and these rules MUST be followed:
Copy link
Collaborator

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.
Copy link
Collaborator

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.

* Microsoft Graph APIs that build on data or functionality provided by third-parties will want to reference the data from those third-parties.
The third-party data that is exposed on Microsoft Graph should be consistent with the data directly coming from the third-party services, but to be referenced by Graph APIs, CSDL entities need to be created and navigated to.
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.
Copy link
Collaborator

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.

* Microsoft Graph is not intended to be a single-pane-of-glass for all third-party APIs.
Copy link
Collaborator

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.

Only APIs that facilitate Graph scenarios should be exposed under `/external`.