From 15abc28027c30a39dc609a9638c922e64b0f7cfd Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Thu, 4 Apr 2024 16:31:51 -0700 Subject: [PATCH 1/4] Create external-top-level-segment.md --- graph/patterns/external-top-level-segment.md | 31 ++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 graph/patterns/external-top-level-segment.md diff --git a/graph/patterns/external-top-level-segment.md b/graph/patterns/external-top-level-segment.md new file mode 100644 index 00000000..07476917 --- /dev/null +++ b/graph/patterns/external-top-level-segment.md @@ -0,0 +1,31 @@ +# `/external` top-level segment + +Microsoft Graph API Design Pattern + +*The `/external` top-level segment is used to expose data that is provided by third-party services.* + + +## Problem + +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. + +## Solution + +In addition to the 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. + +## When to use this pattern + +*Describe when and why the solution is applicable and when it might not be.* + +## Issues and considerations + +Microsoft Graph is not intended to be a single-pane-of-glass for all third-party APIs. +Only APIs that facilitate Graph scenarios should be exposed under `/external`. + +## Example + +TODO show the EPM APIs that expose external auth system data From 4d64fb02f757da69b1d4cb815fcbfcf0170d1000 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 8 Apr 2024 14:17:39 -0700 Subject: [PATCH 2/4] Create graph-taxonomy.md --- graph/articles/graph-taxonomy.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 graph/articles/graph-taxonomy.md diff --git a/graph/articles/graph-taxonomy.md b/graph/articles/graph-taxonomy.md new file mode 100644 index 00000000..f0bc8c9e --- /dev/null +++ b/graph/articles/graph-taxonomy.md @@ -0,0 +1,18 @@ +# Graph Taxonomy + +Different top-level segments have different requirements and these rules MUST be followed: + +* `/external` + + The `/external` top-level segment is used to expose data that is provided by third-party services. + + 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 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. + Only APIs that facilitate Graph scenarios should be exposed under `/external`. From 49677e0ccec79ccd167ff45cd64eeec039a8cc4c Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 8 Apr 2024 14:20:29 -0700 Subject: [PATCH 3/4] Update graph-taxonomy.md --- graph/articles/graph-taxonomy.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/graph/articles/graph-taxonomy.md b/graph/articles/graph-taxonomy.md index f0bc8c9e..8129c46b 100644 --- a/graph/articles/graph-taxonomy.md +++ b/graph/articles/graph-taxonomy.md @@ -4,15 +4,12 @@ Different top-level segments have different requirements and these rules MUST be * `/external` - The `/external` top-level segment is used to expose data that is provided by third-party services. - - Microsoft Graph APIs that build on data or functionality provided by third-parties will want to reference the data from those third-parties. + * The `/external` top-level segment is used to expose data that is provided by third-party services. + * 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 scenario-based APIs, additional APIs should be released under the `/external` top-level segment. + * 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. + * Microsoft Graph is not intended to be a single-pane-of-glass for all third-party APIs. Only APIs that facilitate Graph scenarios should be exposed under `/external`. From 155de257ba8df1e2c6cec3eaa5f5cee719b71304 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 8 Apr 2024 14:20:43 -0700 Subject: [PATCH 4/4] Delete graph/patterns/external-top-level-segment.md --- graph/patterns/external-top-level-segment.md | 31 -------------------- 1 file changed, 31 deletions(-) delete mode 100644 graph/patterns/external-top-level-segment.md diff --git a/graph/patterns/external-top-level-segment.md b/graph/patterns/external-top-level-segment.md deleted file mode 100644 index 07476917..00000000 --- a/graph/patterns/external-top-level-segment.md +++ /dev/null @@ -1,31 +0,0 @@ -# `/external` top-level segment - -Microsoft Graph API Design Pattern - -*The `/external` top-level segment is used to expose data that is provided by third-party services.* - - -## Problem - -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. - -## Solution - -In addition to the 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. - -## When to use this pattern - -*Describe when and why the solution is applicable and when it might not be.* - -## Issues and considerations - -Microsoft Graph is not intended to be a single-pane-of-glass for all third-party APIs. -Only APIs that facilitate Graph scenarios should be exposed under `/external`. - -## Example - -TODO show the EPM APIs that expose external auth system data