Over the past few years, I have occasionally dreamed about what would be my perfect job. Of course it would have to involve HTTP APIs. But beyond that, my background in ERP software leaves me longing for solving business problems for users. My experience at Runscope as a developer advocate reaffirmed my desire to spend time helping other developers. Working with the OpenAPI Initiative over the past couple of years has allowed me to dip my toes into standards work that I have been fascinated with for so long. It’s a curious mix.
I was one of those strange kids that used to tell people that I wanted to work for a large corporation. Many people dream of startup life, being their own boss, whereas I am fascinated by the dynamics of enterprises, the community and the culture. There is something special about the idea of thousands of people working together towards a common goal. At least the theory appeals to me.
Ironically, I spent the first 20 years of my career self-employed. Joining Microsoft was a big change for me, but I was right! The last two and half years at Microsoft have been an amazing experience. It is everything I expected of being a cog in the corporate machine and I love it. The mantra of “One Microsoft” is something that I can really get behind and I genuinely feel that real action is being taken at every level to make it happen.
My intent with this blog post was to get to the point quickly and then provide more details for those who care. Apparently I failed. So without any further context: I believe I found my perfect job. I am moving to a new team at Microsoft. I will be joining Yina Arenas’ team working in the Microsoft 365 developer ecosystem. More specifically, I will be working on the Microsoft Graph developer tooling. In another twist to the story, I’ll be joining as a product manager, not as a developer. Don’t laugh! I’ve been honing my Power Point skills recently.
Momentum: Microsoft Graph
If you didn’t watch the keynotes at Microsoft Build this year, or last year, you may not have heard of Microsoft Graph. It is an HTTP API that provides access to a user’s data that is stored in one of the many services in the Microsoft Cloud. It provides a consistent developer experience whether you are accessing emails in an Outlook Inbox, messages in Teams channel, an Excel worksheet or a file in OneDrive.
In spirit with formation of the Experiences and Devices division, this year saw the introduction of the Windows Timeline API being added to the Microsoft Graph alone with Intune device management APIs. The Identity division who work as partners with E&D on the Microsoft Graph announced a number of security and user management APIs.
It is clear, from the high level vision statements, the services being added, all the way down to the tools and documentation that are being written, that the Microsoft Graph is a cross company strategic effort to make it easier for developers to build products and processes that leverage user’s productivity data that is stored in the Microsoft Cloud.
From a technology perspective, Microsoft Graph uses OData conventions. This is not quite the same as saying it is an OData service. Back when OData first appeared in 2009, the tooling that created OData services made it very easy to take data stores and make them accessible for ad-hoc querying via HTTP. Although this approach has a number of useful applications, it also is an anti-pattern for creating scalable, cost efficient, evolvable HTTP APIs for widespread consumption. The OData specification, the tools, and community have evolved significantly in since its introduction. The payload format is now a much lighter weight JSON format that has some similarities to JSON-LD. Some of the syntax elements have been made optional and many of the capabilities missing in the original specification have been added.
The most important aspect of how OData is used in Microsoft Graph relates to how teams are guided to implement OData capabilities. Teams are directed to build the capabilities that make sense for the service, not to implement capabilities because “that’s what OData services can do”. Where filtering is appropriate, it is implemented with OData syntax. Where navigation properties make sense, the OData conventions are followed. This common sense approach provides services that are tailored to the task but use common conventions that have expected behavior across all the services.
Opportunity: Client Libraries
As much as it pains me to say, HTTP isn’t the easiest application protocol to understand. There are lots of ambiguous scenarios, a number of strange mechanisms due to age and backward compatibility. There are some things in the design that are just plain broken. As much as I have tried to spread the gospel of HTTP for the last ten years… maybe, perhaps, not everyone needs to understand the details of how some of the more obscure interactions work.
Providing client libraries to access an API is taken for granted as an essential part of providing an HTTP API. They eliminate the need to manually create HTTP requests and handle responses and enable developers to focus on dealing with functions and data in terms of the application domain. However, a curious anomaly that I have experienced is, the more experienced API developer, the less likely they are to use a provided client library and more likely will use their own infrastructure to construct the HTTP requests. I hope to dig into the details of why I think this is in a future blog post.
As an industry I believe we have spent an order of magnitude more time building frameworks and tooling to enable developers to provide HTTP APIs that we have to consume them. I believe there is a significant opportunity to provide a better experience for the API consumer.
Don’t take this as a criticism of the existing Microsoft Graph client libraries, because I actually think the existing Microsoft Graph client libraries have some major advantages over many others I have seen. I just think we can go even further.
Momentum: HTTP APIs
I took a career bet on HTTP about 12 years ago, so feel free to consider this commentary self-serving and biased. 
HTTP has powered the web for more than 35 years. Other protocols have emerged to fill gaps where HTTP wasn’t effective. HTTP/2 addresses some of the major performance challenges that have emerged. It also enables some scenarios that previously required switching to other application protocols. It has achieved this without breaking backward compatibility and achieved significant adoption in a fairly short period of time.
The next frontier is the Internet of Things and for the vast majority of devices, HTTP and HTTP/2 are going to be good enough. From what I am seeing in the industry these days, majority of systems integration is done with HTTP. There will always be the need for specialized protocols for specialized scenarios, but HTTP is water to the life of the web.
For developers who are constantly bombarded by the next great technology to learn, I think even 12 years later, the advice to learn how HTTP brings value as an application protocol and not just a data transport protocol is still sound career advice.
Opportunity: Your data, at your fingertips
If you have a Microsoft 365 (or Office 365) subscription, or you have customers that have them, then Microsoft Graph opens up a world of possibilities. Who wants to implement yet another identity store with permissions management capabilities? A cloud based file storage system with format translation capabilities? Task management, contact management, schedule management? Chances are these are all ancillary concerns that are not part of the domain expertise that makes your company or your product valuable to your customers? Some of the services in Microsoft Graph are essential parts of any piece of business software, and others would be really nice to have. Microsoft Graph entities are extensible so that you can choose to attach your domain data to them and many entities allow you to subscribe to change notifications so that you get callbacks when there are changes.
Leveraging the Microsoft Graph by integrating it into new or existing products is a low cost, high return, easy pitch to your customers who already use Microsoft 365. And it opens a whole new set of prospective customers who are already Microsoft 365 users.
Momentum: Microsoft 365 Ecosystem
There is no doubt that Microsoft see cloud based services as a strategic part of their effort for the foreseeable future. Across the company we are seeing efforts to make integration and interoperability seamless. Logic Apps has many connections for interacting with Microsoft Graph based services. Azure Functions has bindings to Microsoft Graph services. Based on my 15 years of building ERP software, I see the potential for integration with Dynamics services to be immense.
Opportunity: OpenAPI
Due to the fact that Microsoft Graph uses OData conventions, it makes sense that it would use the OData metadata language, CSDL, to describe the API. However, there has been demand from customers to provide a description of the API in OpenAPI format. I have recently been working on a library that has a strongly typed C# model for OpenAPI descriptions and readers/writers. One of the teams that I have been working with have been building a related library that creates an OpenAPI description from the CSDL description. We expect to expose these OpenAPI descriptions on the Graph in the coming months.
Momentum: Azure API Management
The downside of moving to a new team is I have to leave my old team. Working on Azure API management has been an amazing experience. It is a team of really smart folks who are passionate about building a great product for our customers. We have seen tremendous growth in the product, we have added a ton of new features and there are some really exciting things coming later this year.
Opportunity: The Future
If you haven’t tried out the Microsoft Graph, go play around in our explorer. If you are already using the Microsoft Graph, I’d love to hear about it. If you have things you wish the client libraries would do for you, make sure I know about it because I want to make that happen.