This document summarizes a Microsoft Graph developer call that covered TLS deprecation for change notifications, the GetResourceSubscriptionPath API, Microsoft Graph versioning strategy, and a partner demo. The call agenda included four presenters and covered TLS deprecation timelines, details on the new GetResourceSubscriptionPath API, an overview of Microsoft Graph's version-independent API evolution approach, and a demo of a case management solution built using Microsoft Graph. The document provides additional details on each topic discussed during the call.

1. Microsoft Graph
Developer community call
TLS Deprecation, GetResourceSubscriptionPath,
Versioning and Partner Demo
Jeremy Thake, Vincent Biret, Arpitha Dhanapathi,
Ásgrímur Skarphéðinsson
March 3, 2020

2. Call agenda

3. Jeremy Thake
@jthake
Vincent Biret
@baywet
Arpitha Dhanapathi
@twitter
Ásgrímur
Skarphéðinsson
@arpi846

4. TLS 1.0 & 1.1 deprecation for
change notifications
subscriptions (webhooks)

8. Feb 17th March 16th April 15th May 15th
POST must (either):
- Upgrade to TLS 1.2
- Include the additional
property
POST must:
- Upgrade to TLS 1.2
PATCH must:
- Upgrade to TLS 1.2
Notifications are not
delivered anymore over
TLS 1.0 or 1.1
PATCH must (either):
- Upgrade to TLS 1.2
- Include the additional
property

10. More
information
Aka.ms/MSGraphWebho
oksTLS

11. GetResourceSubscriptionPath

13. GetResourceSubscriptionPath

14. Microsoft Graph –
API Evolution &
Versioning Strategy

15. Balance
App Dev
Experience
API Agility
Goal

16. Options Considered
Version Pros Cons Who’s doing it
Unified Major • Industry standard (for
enterprise)
• Most familiar to app
developers
• Hard to coordinate
among API developers
• Impacts *all* app
developers
• Google
• Amazon
• Almost
everyone
Per-service • Independence for API
developers
• Hard to understand &
track
• Shows service “silos”
• Azure
Version
Independent
API Evolution
• Least impact to App dev
• Most flexible for API
dev
• Harder to understand &
track
• Not “the enterprise
way” in vogue
• Slack
• Facebook
Cadence 3-5 years Quarterly On-demand Hybrid
Version
Cadence

17. • Publish new "deprecated" API elements quarterly
 Product:
 Marked in Schema as "deprecated" (i.e., going to be removed)
 Still fully supported in queries/responses
 Communications:
 Announced on public forums
 Notifications to app developers
• Remove no sooner than 2 years after announcing
deprecation
 Gradual retirement with monitoring
• Only those applications affected need to react
Proposed Strategy for MS Graph APIs
Version Independent API Evolution

18. • Enables API agility – based on product feedback and quickly bringing
forth right user experiences
• Impacts only subset of app-developers vs everyone
• Less confusion on developers
Proposed Strategy for MS Graph APIs
Why?
• Yes – Many accumulated deprecated properties and/or major protocol changes (e.g.,
requiring $select, or defaulting to OData 4.01 response payloads) could lead to releasing
a new version.
• This will be much less frequent
Will a new version be released ever?

19. App Developer
Experience

20. API Lifecycle
1. Functional
2.
Deprecated
3. Retired 4. Removed
Reduced support/DevEx/
functionality. 2-2.25 years
after marked for
deprecation
Developer experiences discourage
usage of the API element and
attempt to provide an alternative
Developer experiences encourage
use of the API
API no longer callable

21. App dev experience – Changelog
Developers can
register for
notifications on
deprecation changes
Key Developer Experiences:
 HTTP header Responses for deprecated elements
 SDK updates and IntelliSense updates to reflect
deprecation (via compilation warnings etc.)
 Graph explorer experience to reflect deprecation
 Updated to Graph Changelog and API reference docs
 Feature to allow developers to register for email
notifications on changes
 Quarterly blog posts
 Community calls

22. Other ideas (From Community)
 Include URL segments in the deprecation notice, that will allow for searching within logs/calls
 Filtering on changelog and email registration on notifications (to reflect just the APIs that
developers are interested in)
 Make use of M365 admin message center / dev.office.com notification center (allows for RSS
feeds)
 Azure Portal (where apps registered and managed) - users can register for notifications and do
the query on demand to see what has changed/broken
 Azure Marketplace team app certification
 Automated way/bot to automatically detect changes in APIs and show it in a dashboard
 Use telemetry and provide a report that lists which deprecated APIs are being used in a given
tenant and the AAD AppID.
 GitHub app to monitor and notify

23. App dev experience – Functional (API
Resource)

24. App dev experience - Deprecated
• Headers in API responses will indicate deprecation
• Minimum period in deprecation state: 2-2.25 years
• Developer experiences are regenerated to reflect
deprecation
• Changelog aggregates breaking change at top
• API reference docs are visually tagged
• SDK throws compilation warnings
• Graph Explorer updated to reflect the change
• Communications: API-specific deprecation blog
post, email notifications, developer community
calls

25. App dev experience - Retired
• Final, broad communication push
• Developer experiences are updated again to indicate the API
is retired
• Changelog aggregates breaking change at top
• API reference docs are visually tagged
• SDK - Deprecated element is hidden from Intellisense
• API no longer works in Graph Explorer
• Apps continue to work, but progressive degradation
begins, and telemetry monitored to target
communications and whitelisting on a need basis

26. App dev experience - Removed
• Officially removed from metadata
• Disappears from developer experiences and is no
longer callable
• Calling the API always fails unless the app is on explicit
allow list

27. Applicable Change Patterns in APIs
Remove
Rename
Restructure (in-
place type
change)
• Introduce a common suffix (_v2) to existing elements
• 2 cycles and 2 renames
• Example: Convert redirectUris from an array of strings
to an array of complex types
1. Cycle 1: Add redirectUris_v2 as the array of
complex types
2. Let cycle 1 complete (redirectUris is removed)
3. Cycle 2: Add redirectUris back with the array of
• Example: use “firstName” instead of “givenName”
• Example: remove “propertyX”

28. Feedback
Focus Questions:
• Best ways to contact app developers to alert regarding breaking changes
• $Select – should new types introduce $select REQUIRED? (enables better
telemetry on usage of individual properties  targeted communications)
• Should removed APIs be maintained in docs vs removing all traces
completely?
Open Discussion:
Overall Feedback – Pros and Cons

29. Partner Demo
• Case Management
• Project Management
• Timesheet Reporting
KLYNKE.COMF&S
THEGOAL
“Create more business
value for Office365 users by
using Microsoft Graph ”

31. Demo – Case Management
Turning group conversations into
Cases using Microsoft Graph
webhooks and SignalR

32. InitWebHook
„Listen“ Endpoint
Microsoft Graph
MoveConversation
Notify Team
SignalR
InitSignalHub
RequestToNotify
RegisterTeam
Register Case
SDKWebHooks.InitWebook(….
graphClient.Subscriptions.Request().AddAsync(sub);
_cache.SetAsync(SubForCache.Sub.Id, encodedSub);
GetSubFromCache(item.SubscriptionId);
SDKGroupConversation.RealtimeMove
graphClient.Groups[GroupID].Conversations[ConvID]
graphClient.Groups[GroupID].Conversations[id].Threads
SDKGroupSite.AddToMarkCaseListAsync
graphClient.Sites[SiteID].Lists[ListID].Items
C# OnConnectedAsync()
Clients.Caller.SendAsync("InitTeam");
JS connection.on("InitTeam", ()…
connection.invoke("JoinGroup"
C# SendAsync("NewFeedForGroup",groupName….
JS WriteOnScreen(data)
Case Management

34. Demo - Time Sheet
created directly from Outlook Calendar
and Planner Tasks using Microsoft
Graph

35. Outlook Calendar
Microsoft Graph
Planner
Project
SDKCalendar.GetCalendarAsync(AToken, Start, End);
graphClient.Me.CalendarView.Request(queryOptions)
SDKGroupPlan.GetPlanTask(TaskID, AToken);
graphClient.Planner.Tasks[TaskID]
SDKUser.GetCurrentUserPlannerTasksAsync
graphClient.Me.Planner.Tasks.Request()
SDKGroupSite.GetTeamProjects
graphClient.Sites[SiteID].Lists[ListID].Items
SDKGroupSite.GetTeamCases
graphClient.Sites[SiteID].Lists[ListID].Items
SDKCalendar.UpdateEvent(EventID, Description, AToken)
graphClient.Me.Events[EventID].Request().UpdateAsync(Updat
eEvent);
SDKGroupSite.AddToWorkerListAsync
graphClient.Sites[SiteID].Lists[ListID].Items.Request().Ad
dAsync(NewItem);
Case
TIMESHEET
Read From
Write To Outlook Calendar
SharePoint List

37. Thank you
Ásgrímur Skarphéðinsson
asgrimur@klynke.com
www.klynke.com
KLYNKE.COMF&S

38. http://www.m365devpodcast.com/

39. Microsoft 365
https://aka.ms/adaptivecardscommunitycall
https://aka.ms/microsoftgraphcall
https://aka.ms/IDDevCommunityCalendar
https://aka.ms/microsoftteamscommunitycall
https://aka.ms/officeaddinscommunitycall
https://aka.ms/PowerAppsMonthlyCall
https://aka.ms/spdev-call
https://aka.ms/spdev-sig-call
https://aka.ms/spdev-spfx-call
https://aka.ms/M365DevCalls

40. https://aka.ms/M365DevYouTube
(subscribe today)
@Microsoft365Dev
https://aka.ms/MicrosoftGraphCall

41. Q&A