DX, API Design & Documentation

Best practices in software architecture to deliver delightful API products

Image by neo tam from Pixabay
Image by neo tam from Pixabay

Olga Podolyako is a Principal API Architect for Microsoft Graph. In this article, she discusses best practices in software architecture and throws light on some Microsoft products.

Microsoft Graph platform provides access to cloud data and services across Microsoft 365 products, including Office, Teams, Outlook, Azure, Active Directory, etc. Microsoft Graph is centered around the user. That user has multiple data sets, including real tasks, files, and contacts, available in one interconnected system. Microsoft Graph platform has more than 3500 unique resource types and more than 2300 different relationships between them. We receive trillions of data signals from millions of users across Microsoft 365 and Teams. We have over 800 new APIs and enhancements every year.

Considering the platform’s scale, you can see that governance is a challenge.

Historically, we focused only on the consistency of naming, vocabulary, and predictable behavior in compliance with Microsoft Trust guidelines. But as the Graph platform expanded and more products wanted to integrate, we thought of ways to scale up.

We developed a simple entry criterion for when to use APIs and more complex criteria for identifying good APIs and determining their essential characteristics for our API governance. This allows us to prioritize and delegate API-related decisions across all figurative structures and automate API compliance validation.

Software Architecture Method

The architecture is a bridge between business goals and the final resulting system. Software Architecture recommends analyzing and translating business needs into significant architecture requirements, which can then be implemented into a software product. Non-functional requirements or quality attributes, such as security, usability, stability, maintainability, and other aliases, represent an architecture’s significant requirements. In addition to having a big impact on architecture and design, these quality attributes are usually difficult or expensive to change later on.

As a cloud platform, Microsoft Graph offers multiple integration options that allow developers to do people-centric productivity experiences and connect their business systems. We provide granular, restful APIs which communicate synchronously. We have also enabled high-volume customer data ingestion into Microsoft 365 compliance boundary to improve and enrich experiences. We call them graph connectors. We support event-based integration using graph notifications. Event-based integration supports push and pulls mechanisms and multiple delivery channels for notifications using webhooks, event hubs, WebSockets, and event grids.

Based on our experience and analysis of multiple business scenarios, we identified four quality attributes influencing how well an integration option fits into a scenario. These are

  • Data or functionality
  • Data flow direction
  • Data Volume
  • Data latency

To choose the best option for a given scenario, we created a decision flow to guide our customers and product teams. We ask them questions based on their business scenarios. Based on the replies, decision paths are decided, enabling them to make the right choice related to integrating APIs.

This is the entry criterion.

The next thing to look at is goodness criteria. At Microsoft, we have a customer-driven culture. The first question we always ask is, what will the customers get from the product? Graph APIs provide value by enabling customers to build innovative solutions. When customers view business solutions using graph APIs, they expect those APIs to be easy to adopt, secure the supervisor, and be well supported during their entire lifecycle. Effectively, it means that all customers want an API as a product.

In addition, because APIs are Cloud products, you can use established, well-architected frameworks and adopt some essential and generic qualities such as security, operational excellence, and performance.

But we need to remember our organizational business needs. Therefore, by tailoring quality attributes for APIs based on our organizational needs, we arrived at six essential quality attributes; planning, design, security, operational excellence, performance, availability, and usability.

The next step is to document these criteria and principles of API governance and build guidelines. Microsoft Graphs has specific guidelines for specific naming conventions, consistent relationship specification, consistent error processing, and representation. We have supported our deprecated APIs for at least two years. We also have very well-defined structured authorization specifications. We also have a library of reusable design patterns.

As APIs change every week, we have three different review boards to ensure that the APIs meet our standards. We use multiple tools to support our API developers to help them develop better.

Now that we have set our criteria and enabled developers with tools, we have to measure our success. And to measure success, we need metrics. Therefore, we created KPIs for each quality area. These KPIs represent the most important metric in each quality area to foster positive outcomes for our customers. For example, for planning quality, it’s important to have a predictable release schedule to allow customers to plan for changes. For this quality, we measure the age of unpublished test APIs, which indicates how long the API is stuck in a low environment. This is our current important metric.

To summarize –

  • Not every integration is an API
  • Treat APIs as a software product
  • Define API quality for your organization
  • Use APIOps to automate an API lifecycle
  • Provide API quality observability
Olga Podolyako
I'm striving to work in a challenging enterprise environment, where I can benefit my clients by applying my strong architecture and leadership skills to solve complex business and IT problems using modern technologies and architectures, build strong architecture practices to deliver desired business outcomes. • Extensive experience in all enterprise architecture domains - business, data, application, and technology • Proven leadership skills in the area of architecture delivery methodology • Extensive expertise with leading software development teams in the application and integration domain • More than 20 years of experience with end-to-end development lifecycle implementing front-end applications, integration solutions, services, and workflows in compliance with enterprise security standards and industry regulations Specialties: Enterprise Architecture, Integration Architecture, Cloud / Infrastructure Architectures, TOGAF and SEI Software Architecture methodologies

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture