Mike Kistler mikekistler

This gist will show how to extract information from the RESTler speccov.json to get a quick view of what operations succeeded and failed in a RESTler run and why.

The primary tool for this is jq.

Here I will use the results of a RESTler test I ran on the Azure DataBricks service.

The test summary reported at the end of the run was:

Restler + Test Recording Proxy

This gist will describe how to run Restler with the Test Recording Proxy to capture service traffic that that later be validated by the Swagger Accuracy tooling.

We'll use the Azure App Configuration service in this example but the concepts should generalize to any Azure service.

Clone and build Restler

git clone https://github.com/microsoft/restler-fuzzer.git

There are conventions in REST APIs that help users(developers) quickly understand how the resource works. This is the fundamental concept of REST.

Start with the resources

A REST API provides operations on resources and resource collections.

It should be readily apparent from just looking the paths in the REST API what the resources are.

Here is a collection of entity-relationship diagrams for the Azure Load Test service based on just the path structure in the REST API.

Load Test

erDiagram
    LOAD-TEST { 
        string testId
 }

Here is a collection of entity-relationship diagrams I created for the Azure Load Test service based on the Key Concepts in the public documentation.

Test

erDiagram
    TEST {

Running RESTler on the Azure Keyvault service

Create an initial config

Invoke RESTler generate_config, passing a list of the REST API defintion files. This will create a RESTler config file with these files in the SwaggerSpecFilePath.

specs=$(find /Users/mikekistler/Projects/Azure/azure-rest-api-specs/specification/keyvault/resource-manager/Microsoft.KeyVault/stable/2022-07-01 -type f -depth 1)
dotnet $restler_bin/restler/Restler.dll generate_config --specs ${=specs}

Element Ordering for ApiView Swagger view

This document will define a deterministic ordering of fields at every level of an OpenAPI v2 document. ApiView should transform an input document to conform to this ordering.

ref: OpenAPI v2 Specification

Top level

ref: Swagger Object

The thought occurred to me today to recast the Azure SDK Design Principles into a corresponding set of design principles for Azure REST APIs. This only took about 5 minutes and I think could be a nice complement to our REST API Guidelines. What do you think?

Azure REST API Design Principles

Azure REST APIs should be designed to enhance the productivity of developers connecting to Azure services. Other qualities (such as completeness, extensibility, and performance) are important but secondary. Productivity is achieved by adhering to the principles described below:

Idiomatic

The REST API should follow the general design guidelines and conventions for HTTP REST APIs. It should feel natural to a developer familiar with REST.
We embrace the ecosystem with its strengths and its flaws.

Advanced use of Restler for an Azure Service

This gist will describe a more advanced use of Restler for the Azure App Configuration service. The goal of this effort is to identify ways to improve coverage.

This scenario reuses some of the machinery described in How to create Restler config.

Clone and build Restler

git clone https://github.com/microsoft/restler-fuzzer.git

	import { createTypeSpecLibrary } from "@typespec/compiler";
	import { createRule, getLinter } from "@typespec/lint";
	import { isQueryParam } from "@typespec/http";

	export const myLibrary = createTypeSpecLibrary({
	name: "myLibrary",
	diagnostics: {
	"version-policy": {
	severity: "error",
	messages: {