-
Notifications
You must be signed in to change notification settings - Fork 2.7k
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.
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
Add guidance for implementing an external standard on graph #503
base: corranrogue9/externalstandards
Are you sure you want to change the base?
Changes from 3 commits
9f5ef0e
76c4458
e782372
5bedf7c
d156bc7
50ee71f
17e9b00
c00f2a2
956726c
62b0153
22b9686
90e9ca6
8c25785
f2c9d83
e114751
eb46156
e18b48c
83568c5
32bbde2
5c64328
d7daa0b
6ca5135
62a5b44
bbaaa3f
039b8cf
20f2d18
2ad6aed
1a7a6ed
92241e2
a6cc17c
3ff1be6
7b1557f
27ee3ea
49923da
8f218a6
bfb1a8b
630aecd
568d6c0
388b4ce
1615278
ea22528
b3b6b5e
3c4dacf
7653778
8448e5d
e8499d8
0437156
f373897
4f8698e
21c018c
7c7544d
84a7143
f90d48a
641a29e
8ac2a81
8ff72bb
5579a9d
22a90f9
b845104
6529085
8c40492
3431e24
e465ea1
7136424
c77d6cc
7250558
194adeb
6066d21
7482838
3fdf426
9fbcaa5
a50a52c
ab0700f
ddeed9f
67f30db
5f97b29
011dd3c
55e2ef0
57e6d71
5818436
cc8a934
2ca37ff
6aa47c1
c9405c4
34b9192
af4e80a
c7d483c
c6331c4
75385be
076732d
f47f452
50ab124
33faa27
5d907fc
f9d8f70
1982472
59e0cd7
36e6d85
170a899
165393e
400d7ca
b736b80
955e9ec
b7fb275
9c93e8c
978d847
685e493
0674b4c
00c5e08
724b5f7
aded31f
a60faaa
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -14,6 +14,7 @@ Table of contents | |
- [Behavior modeling](#behavior-modeling) | ||
- [Error handling](#error-handling) | ||
- [Enums](#enums) | ||
- [External Standards](#external-standards) | ||
- [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes) | ||
- [Versioning and deprecation](#versioning-and-deprecation) | ||
- [Recommended API design patterns](#recommended-api-design-patterns) | ||
|
@@ -328,6 +329,19 @@ For a complete mapping of error codes to HTTP statuses, see | |
|
||
<a name="api-contract-and-non-backward-compatible-changes"></a> | ||
|
||
## External standards | ||
|
||
For ease of client use and interoperatibility, some APIs should implement a standard that is defined external to Microsoft Graph and OData. | ||
Workloads should follow these standards exactly, even if they conflict with the OData standard and/or the Microsoft Graph guidelines. | ||
Workloads must define these standards in their CSDL model if they do not conflict with the OData standard. | ||
Standards that *do* conflict with the OData standard may be defined in the CSDL in one of two ways: | ||
1. Using `Edm.Untyped` only and support for the external standard will come directly from the service implementation; OR | ||
2. Adding CSDL elements to model the external standard using `Edm.String` for `EnumType`s that conflict with the OData standard and `Edm.Untyped` wherever any other conflict with the OData standard occurs | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. From Mike: The structuring of the conjunction makes this sentence seem like it's only about enums There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The allowed values annotaiton should be used for strings |
||
|
||
In either case, any use of `Edm.String` instead of an `EnumType` or any use of `Edm.Untyped` must provide a [description annotation](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.xml#L105) to document references to the standard that the client is expected to follow. | ||
The benefit of the second approach is that strongly-typed models have SDK support for clients and also have significant tooling support for both the workload and clients. | ||
Note that it is backwards compatible for a workload to migrate from the second approach to the first approach in case the external standard is *initially* compliant with the OData standard and *later* conflicts with the OData standard. | ||
|
||
## API contract and non-backward compatible changes | ||
|
||
The Microsoft Graph definition of breaking changes is based on the | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From Mike, I should be clear what APIs "conflict with odata stnadrad/graph guidelines"