Conventions
Base URL, versioning and content type
Section titled “Base URL, versioning and content type”- All data routes live under
/exchange/v1.0/. - Requests and responses are
application/json; write bodies are JSON. - The contract is published two ways: CSDL at
/exchange/v1.0/$metadataand OpenAPI 3 at/openapi/v1.json. - Within
v1.0, changes are additive; a breaking change would bump the segment (v1.0→v2.0).
URL conventions: the Graph and cmdlet hybrid
Section titled “URL conventions: the Graph and cmdlet hybrid”| Concept | Convention | Example |
|---|---|---|
| Collection | GET /collection |
GET /exchange/v1.0/mailboxes |
| Single entity by key | GET /collection/{key} |
GET /exchange/v1.0/mailboxes/[email protected] |
| Alternate-key lookup (Graph-style) | GET /collection(prop='value') |
GET /exchange/v1.0/mailboxes(userPrincipalName='[email protected]') |
| Singleton | GET /singleton (no key) |
GET /exchange/v1.0/atpPolicyForO365 |
| Sub-resource collection | GET /collection/{key}/sub |
GET /exchange/v1.0/mailboxes/{key}/permissions |
| Link relationship write | POST/DELETE …/{rel}/$ref |
POST /exchange/v1.0/distributionGroups/{key}/members/$ref |
| Owned-entity write | POST/PATCH/DELETE /collection[/{key}] |
POST /exchange/v1.0/mailboxes/{key}/permissions |
Keys accept whatever the cmdlet’s -Identity accepts - UPN, alias, primary SMTP, GUID, or
display name. The alternate-key form (userPrincipalName='…') works for the recipient families
and is declared in $metadata (so generic OData tooling can discover it); a permissive middleware
unwraps it before routing.
Body shape rule (the project’s cardinal convention): Graph-style URLs, cmdlet-aligned bodies.
A membership add is { "member": "[email protected]" } (the cmdlet’s -Member), not an @odata.id
wrapper. A Set-* PATCH carries only the cmdlet’s accepted params, camelCased
(-AccessRights → "accessRights").