I wanted to update you all on a breaking change that we are making to the Outlook REST API Beta endpoints.  This change is the introduction of a Request Validator which is going to be deployed worldwide over the next few weeks.  Here are the details of this change.

What is the Request Validator?

The Request Validator is a module that checks the validity of incoming requests based on the following

• Annotation restrictions in the Edm Model, namely
  • Search
  • Expand
  • Navigation
  • Change Tracking
  • Insert
  • Update – (Patch/Merge)
  • Delete
• Http methods allowed for a specific resource or collection (e.g. GET, POST, PATCH/MERGE, DELETE)

Why add a Request Validator?

• To catch invalid requests early on before sending the request downstream
• To adhere to the expected behavior based on the OData Model for transparency. The Odata model uses annotations to describe its capabilities (what an app can or cannot do)

• To conform to the OData Spec on what requests are permitted for a given http method

What is the impact of introducing the Request Validator?

• Developers might need to rewrite some requests if these requests are not consistent with the model – as the request validator will throw an Exception if it fails to validate the request
• Developers can expect consistent behavior that is based on the annotation specified in the Edm model
• Developers might need to rewrite test cases for queries that fails the request validator

Exceptions

1. Insert
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode: InsertNotSupported
   3. Message: ErrorRequestValidatorInsertNotPermitted(string propertyName) = Insert is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
2. Update
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode: UpdateNotSupported
   3. Message: ErrorRequestValidatorUpdateNotPermitted(string propertyName) = Update is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
3. Delete
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode: DeleteNotSupported
   3. Message: ErrorRequestValidatorDeleteNotPermitted(string propertyName) = Delete is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
4. Navigation
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode: NavigationNotSupported
   3. Message:
      1. ErrorRequestValidatorNavigationNotPermitted(string propertyName) = Navigation is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
      2. ErrorRequestValidatorRecursiveNavigationNotPermitted(string propertyName) = Recursive navigation is not permitted after property ‘{0}’ according to the annotation specified in the Edm model.
5. Search
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode: SearchNotSupported
   3. Message:
      1. ErrorRequestValidatorSearchNotPermitted(string propertyName) = Search is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
      2. ErrorRequestValidatorSearchNotPermittedForSegment = Only NavigationProperties and EntitySets are searchable
6. Expand
   1. HttpCode: HttpStatusCode.BadRequest = 400
   2. StringCode:  ExpandNotSupported
   3. Message: ErrorRequestValidatorExpandNotPermitted(string propertyName) = Expand is not permitted for property ‘{0}’ according to the annotation specified in the Edm model.
7. Default

1. • Will be throwing the existing ODataResponseException with custom message
     1. HttpCode: HttpStatusCode.MethodNotAllowed = 405
     2. StringCode: ErrorInvalidRequest
     3. Message: ErrorRequestValidatorMethodNotAllowed(string method, string propertyName) = Method ‘{0}’ not allowed for ‘{1}’

Example:

1. Navigation restriction placed on a navigation property

GET  https://outlook.office.com/api/beta/me/events(‘id’)/calendars(‘id’)/events(‘id’)

This request throws an exception as Recursive navigation is not permitted after property ‘events’

Looking in the metadata for the Calendar Entity, the navigation property Events has the navigation annotation where the navigation type set as single. This means you can navigate upto https://outlook.office.com/api/beta/me/events(‘id’)/calendars(‘id’)/events but not beyond.

The following segments may be appended after the navigation property

1. 1. • Count segment  /$count
      • Batch segment /$batch
      • Value segment /$value
      • Navigation property link segment /$ref

2. When sending invalid segment for the http method

POST https://outlook.office.com/api/beta/me/message(‘id’)

This request throws an exception as key segment is not allowed for post

http code: 405

string code: ErrorInvalidRequest

message: Method ‘POST’ not allowed for ‘Microsoft.OData.Core.UriParser.Semantic.KeySegment’

– Abdelkader Bahgat on behalf of the Outlook Ecosystem team