Be careful to case sensitivity in Microsoft Graph REST API

Last week during Connect(); // 2015, Microsoft announced the general availability (GA) of Microsoft Graph (formerly known as Unified API).

In association with the announcement, a brand new website with a full documentation that explains what’s Microsoft Graph and how to use the REST API was launched here : http://graph.microsoft.io/docs

Since few days, I’m working with Microsoft Graph and I found few issues. Today, I want to talk about one of them which is common with a lot of APIs but frustrating when you encounter it.

During my investigations, I was trying to send a mail and by refering the documentation, it’s noted that you just have to send a JSON message like this one…

["message": {
  body = {
    content = "This message was sent with Microsoft Graph",
    contentType = "text"
  },
  importance = "high",
  subject = "Microsoft Graph REST API",
  toRecipients = ({
    emailAddress = {
      address = "john@doe.com",
      name = "John Doe"
    }
  })
},
"saveToSentItems": false]

… to the following URL.

https://graph.microsoft.com/v1.0/me/microsoft.graph.sendMail

Very easy in theory but when I execute the request with these values, I receive the following error message.

One or more parameters of the operation 'SendMail' are missing from the request payload. The missing parameters are: Message.

To understand what’s the problem, I looked at the metadata generated for the REST API (based on OData 4.0) by accessing the following URL.

https://graph.microsoft.com/v1.0/$metadata

In the metadata returned by the server, you can see this.

<Action Name="sendMail" IsBound="true" EntitySetPath="bindingParameter">
<Parameter Name="bindingParameter" Type="microsoft.graph.user" />
<Parameter Name="Message" Type="microsoft.graph.message" Nullable="false" />
<Parameter Name="SaveToSentItems" Type="Edm.Boolean" />
</Action>

As you can see, the parameters used by this method are named “Message” and “SaveToSendItems” (in PascalCase) and not “message” and “saveToSendItems” (in lowerCamelCase) as written in the documentation.

When you pay attention to metadata generated by OData, you will see that some methods, especially those existing in other parts of Office 365 REST APIs (e.g. sendMail is used in Outlook REST API), still use PascalCase for their parameter names.

So if you follow the documentation to implement Microsoft Graph but you receive an error message indicating that a parameter is missing, take a look at metadata generated by OData to validate that the method is not expected to use PascalCase instead of lowerCamelCase for its parameters.

Advertisements

6 thoughts on “Be careful to case sensitivity in Microsoft Graph REST API

  1. Pingback: Episode 074 on Microsoft Graph with Yina Arenas—Office 365 Developer Podcast | X-Vision IT Consulting GmbH

  2. Yina Arenas

    Stephane, thank you for the great article, I’m happy to share that this issue that you found and reported has now been fixed in the API. While we can’t update the metadata without introducing a breaking change, we fixed the case sensitivity and you can call the sendMail action using camelCase parameters.

    Like

    Reply
  3. Pingback: Office 365—monthly Dev Digest for December | nokipedia.com

  4. Pingback: Office 365—monthly Dev Digest for December | Alt-Tech

  5. Pingback: Episode 074 on Microsoft Graph with Yina Arenas—Office 365 Developer Podcast | Com-Tech of Miami, Inc.

  6. Pingback: Episode 074 on Microsoft Graph with Yina Arenas—Office 365 Developer Podcast | Alt-Tech Inc.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s