mikekistler

Before I ride off into the sunset, I thought I should share with you some of the tools that I use in REST API reviews, in case these might be helpful to anyone.

I know we have nearly completed the transition to TypeSpec across all of Azure, but I still prefer reviewing the OpenAPI as I am very familiar with the OpenAPI standard and there are some good tools available to aid in the review. And TypeSpec, for all its benefits, does not really support reviewing a REST API as well as it should, though I understand there is work underway to improve this (mainly highlighting suppressions / deviations from TypeSpec Azure Core).

The main tool I use in REST API reviews is the Spectral linter with a ruleset specifically designed to check

mikekistler

sequenceDiagram
    participant Server
    participant Client as Client/Host
    actor User
    participant LLM

    Note over Server,Client: Initial request with tools

mikekistler

graph TD
  subgraph M365 Agents SDK
    Core[Microsoft.Agents.Core]
    Auth[Microsoft.Agents.Authentication]
    AuthMsal[Microsoft.Agents.Authentication.Msal]
    Builder[Microsoft.Agents.Builder]
    BuilderDialogs[Microsoft.Agents.Builder.Dialogs]
    Client[Microsoft.Agents.Client]
    Connector[Microsoft.Agents.Connector]

mikekistler

Best Practices for MCP Server change

MCP Servers that are accessed over HTTP can be versioned "on the fly" and even transparently to clients through the use of reverse proxies or load balancers, which are used to provide scalability and fault-tolerance.

This introduces challenges for ensuring minimal disruption to clients from deployment of new versions of an MCP Server.

Servers should not expect or require clients to update their list of tools, prompts, or resources.

Breaking changes

mikekistler

sequenceDiagram
    participant Sender
    participant Receiver

    Note over Sender,Receiver: Request with progress token
    Sender->>Receiver: Method request with progressToken

    Note over Sender,Receiver: Progress updates
 Receiver-->>Sender: Progress notification (0.2/1.0)

mikekistler

This is my attempt to get the Traits overlay example working with Speakeasy's overlay tooling.

The original example is here.

Original OpenAPI

openapi: 3.1.0
info:
 title: API with a paged collection

mikekistler

API-ly Ever After: OpenAPI in .NET 9

References

OpenAPI

• OpenAPI Specification
• Spectral Linter
• Scalar UI
• OpenAPI Tools

mikekistler

The PR pipeline checks every PR to determine if it (potentially) introduces breaking changes or violates Azure Versioning policy.

The main tool for this is "openapi-diff" which checks two versions of an OpenAPI doc (old and new) and identifies all the "substantive changes" (changes in descriptions and such are ignored).

Our versioning policy requires that any "substantive change" be done in a new API version.

A subset of the "substantive changes" are also considered a "breaking change"

We add labels to the PR as follows:

• IF any change is classified as breaking AND the "old" OpenAPI doc is GA (same or different than new API version)

mikekistler

Proposal for new Breaking Change Labels

Update of proposal from this comment.

Breaking Changes

BreakingChangeReviewRequired

• Added by automation when it detects a breaking change from a previous GA API version
• Blocks merge until a "BreakingChange-Approved*" label is applied

mikekistler

Resources / relationships for Microsoft DevBox

erDiagram
    Project { 
        string name
    }
    
    Catalog {
 string name