{"id":6490,"date":"2021-06-24T08:51:08","date_gmt":"2021-06-24T16:51:08","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=6490"},"modified":"2021-06-24T08:51:08","modified_gmt":"2021-06-24T16:51:08","slug":"attention-breaking-changes-coming-to-the-microsoft-graph-userpurpose-api-beta","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/attention-breaking-changes-coming-to-the-microsoft-graph-userpurpose-api-beta\/","title":{"rendered":"Attention: breaking changes\u00a0coming\u00a0to the Microsoft Graph\u00a0userPurpose\u00a0API (beta)\u00a0"},"content":{"rendered":"

We\u2019re announcing some upcoming breaking changes\u00a0to\u00a0the Microsoft Graph\u00a0<\/span>userPurpose<\/span><\/a> API (beta). This API enables developers to differentiate the purpose of a mailbox in Exchange Online. For example, a mailbox may belong to a single user, multiple users, a conference room or even a piece of equipment.\u00a0<\/span>\u00a0<\/span><\/p>\n

We are planning to take the\u00a0userPurpose\u00a0API offline for some pre-production updates. During\u00a0this time,\u00a0calls to the API will fail.\u00a0We\u00a0are aware of\u00a0several\u00a0apps taking a\u00a0dependency\u00a0on this\u00a0beta\u00a0API. To mitigate the impact of this downtime, we\u00a0are making\u00a0another\u00a0<\/span>*temporary*<\/span><\/b>\u00a0API called\u00a0<\/span>userPurposeV2<\/span><\/i> available to minimize disruption to these apps. We anticipate that our updates will take up to twelve weeks and we will provide the community with an update when we\u2019ve established a firm work completion date. After we have deployed our planned updates, developers must switch back <\/span>to the\u00a0userPurpose\u00a0API.\u00a0We will t<\/span>he<\/span>n\u00a0deprecate\u00a0the<\/span>\u00a0<\/span>*temporary*\u00a0<\/span><\/b>userPurposeV2 API<\/span>\u00a0in 60 days\u2019\u00a0time.<\/span><\/p>\n

\u202f<\/span>These changes will be rolling out to the Microsoft Graph beta endpoint on\u00a0<\/span>August 24, 2021.\u00a0<\/span><\/p>\n

\u202f<\/span>We would like to again remind our developers that we do not encourage usage of beta APIs in production applications as they are subject to such breaking changes.<\/span>\u00a0<\/span><\/p>\n

\u202f<\/span>What is the change?<\/span><\/b>\u00a0<\/span><\/h4>\n

The beta userPurpose API is scheduled to undergo fixes which must happen offline. During the maintenance interval all calls to the API will fail with the following error. <\/span>\u00a0<\/span><\/p>\n

Bad Request -\u202f400<\/span>\u00a0<\/span><\/p>\n

{\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\"error\": {\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"code\":\u00a0\"BadRequest\",\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"message\":\u00a0\"Resource not found for the segment 'userPurpose'.\",\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"innerError\": {\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"date\":\u00a0\"\u2026\",\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"request-id\":\u00a0\"\u2026\",\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"client-request-id\":\u00a0\"\u2026\"\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}\u00a0\n\n\u00a0\u00a0\u00a0\u00a0}\u00a0\n\n}<\/pre>\n
Apart from internal fixes, the permission model needed\u00a0to access the API\u00a0will\u00a0undergo some changes\u00a0going forward.<\/span>\u00a0<\/span><\/p>\n
What do I need to do?<\/span><\/b>\u00a0<\/span><\/p>\n
If you are dependent on the functionality provided by this API, please update your code to call the\u00a0<\/span>*temporary*<\/span><\/b>\u00a0userPurposeV2 API instead (GET\u00a0<\/span>https:\/\/graph.microsoft.com\/beta\/me\/mailboxSettings\/userPurposeV2<\/span><\/a>). The\u00a0temporary API\u00a0will provide the same response as the current\u00a0userPurpose\u00a0API.\u00a0<\/span>\u00a0<\/span><\/p>\n
You can use the following code-snippet to catch the exception:<\/span>\u00a0<\/span><\/p>\n
try\u00a0\n\n{\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Uri\u00a0Uri\u00a0= new Uri(\"https:\/\/graph.microsoft.com\/beta\/users\/<Id>\/mailboxSettings\/UserPurpose\");\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0httpResult\u00a0=\u00a0httpClient.GetStringAsync(Uri).Result;\u00a0\n\n}\u00a0\n\ncatch (AggregateException\u00a0e)\u00a0\n\n{\u00a0\n\n\u00a0\u00a0\u00a0\u00a0System.Net.Http.HttpRequestException\u00a0innerException\u00a0=\u00a0e.InnerException\u00a0as\u00a0System.Net.Http.HttpRequestException;\u00a0\n\n\u00a0\u00a0\u00a0 if (innerException?.StatusCode\u00a0==\u00a0System.Net.HttpStatusCode.BadRequest)\u00a0\n\n\u00a0\u00a0\u00a0 {\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Uri\u00a0Uri\u00a0= new Uri(\"https:\/\/graph.microsoft.com\/beta\/users\/<Id>\/mailboxSettings\/UserPurposeV2\");\u00a0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0httpResult\u00a0=\u00a0httpClient.GetStringAsync(Uri).Result;\u00a0\n\n\u00a0\u00a0\u00a0 }\u00a0\n\n}<\/pre>\n
Once the original\u00a0userPurpose\u00a0API is fixed and back up, you\u00a0<\/span>will<\/span>\u00a0need to switch back to the original API.<\/span>\u00a0<\/span><\/p>\n
Testing new features for your\u00a0apps\u00a0using\u00a0beta APIs like this one on the\u00a0Microsoft Graph\u00a0API? Help us shape\u00a0its future.\u00a0 The\u00a0Microsoft Graph CPx team runs a\u00a0Fellowship of the Graph TAP (Technology Adoption Program). This group is a combination of Microsoft Valuable Professionals (MVPs), Regional Directors (RDs), and Independent Software Vendors (ISVs) actively working with Microsoft Graph. If you want to be part of the TAP and receive notifications around changes like this, please complete the\u00a0<\/span>TAP\u00a0submission form<\/span><\/a>\u00a0for consideration.<\/span><\/p>\n
\u00a0<\/span>\u00a0<\/span><\/p>\n
\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
The\u00a0userPurpose\u00a0API will be offline for some pre-production updates. To mitigate the impact of this downtime, we\u00a0are making\u00a0another\u00a0*temporary*\u00a0API called\u00a0userPurposeV2.<\/p>\n","protected":false},"author":69077,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-6490","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph"],"acf":[],"blog_post_summary":"
The\u00a0userPurpose\u00a0API will be offline for some pre-production updates. To mitigate the impact of this downtime, we\u00a0are making\u00a0another\u00a0*temporary*\u00a0API called\u00a0userPurposeV2.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6490","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69077"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=6490"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6490\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=6490"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=6490"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=6490"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}