|
2 | 2 |
|
3 | 3 | Microsoft Graph API Design Pattern
|
4 | 4 |
|
5 |
| -### *The Namespace provides the ability to group resource definitions together into a logical set.* |
| 5 | +### *The Namespace provides the ability to organize resource definitions together into a logical set.* |
6 | 6 |
|
7 | 7 | ## Problem
|
8 | 8 |
|
9 | 9 | When building a complex offering API designers may need to model many different
|
10 | 10 | resources and their relationships. For better user experience and
|
11 |
| -discoverability related API definitions need to be grouped together. Large API |
12 |
| -surface may need to be partitioned to generate light-weight client SDKs and |
13 |
| -libraries. |
| 11 | +discoverability related API elements need to be clustered together. |
| 12 | + |
14 | 13 |
|
15 | 14 | ## Solution
|
16 | 15 |
|
17 | 16 | API designers can use the Namespace attribute of the CSDL schema to declare a
|
18 |
| -namespace and logically bundle related API entities in the Graph metadata. |
| 17 | +namespace and logically organize related API entities in the Graph metadata. |
19 | 18 |
|
20 | 19 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML
|
21 | 20 | <Schema Namespace="microsoft.graph.{namespace}">
|
22 | 21 | ...
|
23 | 22 | </Schema>
|
24 | 23 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
25 | 24 |
|
26 |
| -All resources declared within the namespace will be grouped together in the |
27 |
| -public Graph metadata and may be used for partitioning. |
28 |
| - |
29 | 25 | A public namespace must have "microsoft.graph.” prefix and be presented in camel
|
30 | 26 | case, i.e microsoft.graph.myNamespace.
|
31 | 27 |
|
32 |
| -When type casting is required in the API query, request or response a fully |
| 28 | +When type casting is required in the API query, request or response, a fully |
33 | 29 | qualified type name is represented as concatenation of a namespace and a type
|
34 |
| -name. Consequently namespace should be aligned with API category path segment. |
| 30 | +name. Consequently namespaces should be aligned with API category path segment. |
35 | 31 |
|
36 | 32 | ## When to Use this Pattern
|
37 | 33 |
|
|
0 commit comments