# API Service Contracts

> Generate API and service communication contracts with sequence diagram

- Skill: `microsoft/api-service-contracts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add microsoft/api-service-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/api-service-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/api-service-contracts

---


# API & Service Communication Contracts

Analyze the project to document all services, API endpoints, communication patterns (sync/async), DTOs, and retry/circuit-breaker policies. Generate a Mermaid sequence diagram showing the primary request flow across services. Save to `.github/modernize/assessment/engines/facts/api-service-contracts.md`.

## Input Parameters

- `workspace-path` (optional): Path to the project to analyze (defaults to current directory)

## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block

Mermaid sequenceDiagram is unforgiving in a few specific ways: one bad alias or one missing `end` crashes the **whole** diagram with `Syntax error in text`, not just the offending line. Stay strictly inside this subset for the sequence diagram in Step 7:

1. **Chart kind.** `sequenceDiagram` only. Never `sequence-diagram`, never `sequence`.
2. **Participants.** Always declare with the alias form `participant <AlphaNumId> as "Display Label"`. The id must match `[A-Za-z][A-Za-z0-9_]*`. Never omit the id — even a one-word participant should be `participant Client as "Client"`. This is the single biggest cause of past failures.
3. **Arrows.**
   - `->>` synchronous request
   - `-->>` synchronous response (or async return)
   - `-)` async fire-and-forget
   - Message text goes after `:` and is plain text — keep it short and on one line.
4. **Blocks.** `alt` / `else` / `opt` / `loop` / `par` / `critical` MUST be closed by `end` on its own line. Every open block must have a matching `end`. Missing `end` is the #2 cause of past failures.
5. **No line breaks anywhere.** The escape `\n` was removed in modern Mermaid. Aliases, message text, and `Note over` content must all be single-line. Split a long note into multiple consecutive `Note over` lines; split a long message into multiple arrows. This is the #1 cause of past failures.
6. **Banned characters inside participant aliases specifically** (message text is more permissive — only `\n` is banned there):

   | Banned in alias | Why it breaks | Replacement |
   |---|---|---|
   | `\n` (literal two chars) | escape removed | drop |
   | `"` (a second double-quote) | closes the alias early | `'` (single quote) |
   | `` ` `` (backtick) | breaks alias quoting | drop |
   | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` |
   | `:` | confuses with message delimiter | rephrase, e.g. `"REST API (port 8080)"` not `"REST API: port 8080"` |
   | `<br/>` | not interpreted inside aliases | rephrase as shorter alias |

7. **Quote the alias.** `participant Svc as "Order Service"` — never `participant Svc as Order Service` (unquoted multi-word aliases break).

### Mandatory self-attestation

Immediately before writing the ` ```mermaid ` opening fence in Step 7, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation):

```
<!-- mermaid-checked: every participant uses `participant Id as "Label"`, no \n in aliases/messages/notes, every alt/opt/loop closed by end, no `:` inside any alias -->
```

If you cannot truthfully emit that comment, fix the diagram first.

---

## Scope Boundaries — Avoid Redundancy with Other Skills

This skill is part of a set of four complementary assessment skills. To avoid content duplication across their output documents, observe these scope rules:

- **Introduction**: Write a 1-2 sentence intro focused on the API surface (number of endpoints, communication style). Do NOT restate the application's technology stack, database options, or architecture type — those are covered by other skills.
- **Entity fields and persistence details** are owned by the `data-architecture` skill. In the DTOs & Contracts section, list entity/DTO **class names** and their role in the API contract (request type, response type, immutability). Do NOT reproduce full field lists, ORM annotations (cascade, fetch strategy), or table names — reference `data-architecture.md` instead.
- **Validation rules** (e.g., `@NotBlank`, custom validators) are owned by the `business-workflows` skill. Mention validation only when it affects the API contract (e.g., "returns 400 if validation fails"). Do NOT enumerate individual field constraints.
- **Caching implementation details** (provider, TTL, configuration class) are owned by the `data-architecture` skill. In the sequence diagram, you may show cache hit/miss behavior, but do NOT repeat the cache provider name, configuration details, or rationale.
- **Configuration properties and profiles** (e.g., `spring.jpa.*`, database profiles) are owned by the `configuration-inventory` skill. Do NOT list property keys/values.
- **Startup dependency chain details** (readiness probes, K8s manifests, dockerize) are owned by the `configuration-inventory` skill. Mention startup order only if it directly affects API availability. Do NOT repeat probe paths or wait mechanisms.

## Execution Steps

### Step 1: Generate Service Catalog Section

Identify all independently deployable services/modules and produce the complete `## Service Catalog` section:

- Multi-module builds: Maven modules (`pom.xml` `<modules>`), Gradle subprojects (`settings.gradle`), .NET solutions (`.sln` → `.csproj` projects), monorepo workspaces (`package.json` workspaces)
- Docker Compose services (`docker-compose.yml` service definitions) — note third-party containers vs source-built services
- Kubernetes deployments, Helm charts, or IaC definitions

For each service extract:
- Service name and Maven module / project name
- Port number (from config files, `docker-compose.yml`, or `application.properties`/`appsettings.json`)
- Category: **API Layer** (gateways, BFFs), **Business** (domain services), **Infrastructure** (config, discovery, admin), **Observability** (tracing, metrics, dashboards)
- Purpose (one-line description)
- Key framework dependencies (from `pom.xml`, `.csproj`, `package.json`)

### Step 2: Generate API Endpoints Inventory Section

Scan source code for API endpoint definitions and produce the complete `## API Endpoints Inventory` section:

- Java (Spring): `@RestController`, `@Controller`, `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@RequestMapping`
- Java (Jakarta EE): `@Path`, `@GET`, `@POST`, `@PUT`, `@DELETE` (JAX-RS)
- .NET (ASP.NET Core): `[ApiController]`, `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[Route]`
- JavaScript/TypeScript: Express routes (`app.get`, `app.post`, `router.get`), Fastify routes, NestJS decorators (`@Get`, `@Post`)

For each endpoint extract:
- HTTP method (GET, POST, PUT, DELETE, PATCH)
- URL path (including path parameters)
- Request type (body/query/path parameters, DTO class name)
- Response type (DTO class name, status codes)
- API versioning scheme if present (URL path, header, query parameter)
- Which service/controller it belongs to

### Step 3: Generate Management & Observability Endpoints Section

Identify management and observability endpoints and produce the complete `## Management & Observability Endpoints` section:

- Spring Boot Actuator endpoints (`/actuator/health`, `/actuator/info`, `/actuator/metrics`, `/actuator/prometheus`)
- .NET health checks (`/health`, `/healthz`), Swagger UI (`/swagger`)
- Custom metrics annotations: `@Timed` (Micrometer), `[Meter]`, custom metric registrations — note the metric name and which service exposes it

### Step 4: Generate DTOs & Contracts Section

Analyze DTO and contract definitions and produce the complete `## DTOs & Contracts` section:

- Find DTO / request / response model classes (records, POJOs, C# records/classes). List class names and their API role (request body, response, path/query param). Do NOT reproduce full field lists or ORM annotations — those belong in `data-architecture.md`.
- **Distinguish gateway-level DTOs** (aggregation/composition models that combine data from multiple services) from **service-level domain entities** (owned by a single service)
- Note which DTOs are immutable (Lombok `@Value`, Java records, C# records, frozen data classes)
- Identify OpenAPI/Swagger specifications (`openapi.yaml`, `swagger.json`, Springdoc/Swashbuckle annotations)
- Check for protobuf schemas (`.proto` files) or GraphQL schemas
- Note serialization configuration (Jackson, System.Text.Json, custom serializers)

### Step 5: Generate Communication Patterns Section

Identify inter-service and intra-service communication and produce the complete `## Communication Patterns` section:

- **Synchronous**: REST (HttpClient, RestTemplate, WebClient, Feign), gRPC, direct method calls
- **Asynchronous**: Message queues (Kafka, RabbitMQ, Azure Service Bus, SQS), event-driven patterns, pub/sub
- **Resilience patterns**: Circuit breaker (Resilience4j, Polly, Spring Retry), retry policies, timeout configuration, bulkhead patterns — note specific timeout values and fallback behavior
- **Service discovery**: Eureka, Consul, Kubernetes DNS, Azure Service Discovery — note whether services register by logical name or hardcoded URL
- **API gateway**: Spring Cloud Gateway, Ocelot, Kong, custom gateway patterns
- **Gateway aggregation/composition**: Document how the gateway combines responses from multiple backend services (e.g., fetching owner details from one service and visit history from another, then merging them into a single response). Note the composition logic and fallback behavior when a downstream service is unavailable.
- **Client-side load balancing**: Spring Cloud LoadBalancer, Ribbon, or framework-provided balancing
- **Startup dependency chain**: Briefly note the service startup order if it affects API availability. For full details (probes, wait mechanisms, timeouts), refer to `configuration-inventory.md`.
- **Security posture**: Note whether transport security (HTTPS/TLS), authentication (JWT, OAuth2, Basic Auth, Spring Security), or authorization (RBAC, `@PreAuthorize`, role checks) are implemented at the API level. If absent, state it explicitly — e.g., "No authentication or TLS configured; all endpoints are publicly accessible with no authorization checks." Do NOT duplicate CWE security scan findings; focus only on presence or absence at the API contract level.

### Step 6: Generate Service Technology Matrix Section

For each service, identify which cross-cutting capabilities it uses and produce the complete `## Service Technology Matrix` section:

- Web framework (MVC, Reactive/WebFlux, Minimal API)
- Data access (JPA, EF Core, Mongoose, etc.)
- Service discovery (client, server, or none)
- Gateway functionality
- Actuator/health checks
- Caching layer
- Metrics export (Prometheus, Application Insights, etc.)

### Step 7: Generate Service Communication Sequence Section

Create a **Mermaid `sequenceDiagram`** and produce the complete `## Service Communication Sequence` section (re-read the Safety Constraints above before writing):
- Show key actors: Client, API Gateway (if present), Controllers, Services, External Services, Message Brokers
- Annotate synchronous calls with solid arrows and asynchronous calls with dashed arrows
- Include request/response types where relevant
- Show error handling paths for critical flows (circuit breaker, retry)
- For gateway aggregation flows, show how multiple downstream calls are composed

Reference example (this block satisfies every Safety Constraint — match its shape):

<!-- mermaid-checked: every participant uses `participant Id as "Label"`, no \n in aliases/messages/notes, every alt/opt/loop closed by end, no `:` inside any alias -->
~~~mermaid
sequenceDiagram
    participant Client as "Client"
    participant Gateway as "API Gateway"
    participant CustSvc as "Customers Service"
    participant VisitSvc as "Visits Service"
    participant DB as "Database"

    Client->>Gateway: GET /api/gateway/owners/1
    Gateway->>CustSvc: GET /owners/1
    CustSvc->>DB: findById(1)
    DB-->>CustSvc: Owner + Pets
    CustSvc-->>Gateway: OwnerDetails(pets=[Pet1,Pet2])
    Gateway->>VisitSvc: GET /pets/visits?petId=1,2
    alt Visits Service Available
        VisitSvc->>DB: findByPetIdIn([1,2])
        DB-->>VisitSvc: Visits list
        VisitSvc-->>Gateway: Visits(items=[...])
    else Circuit Breaker Open
        Gateway-->>Gateway: Fallback - empty visits
    end
    Gateway->>Gateway: Merge visits into pets
    Gateway-->>Client: 200 OwnerDetails + Visits
~~~

### Step 8: Save Output

Save to `.github/modernize/assessment/engines/facts/api-service-contracts.md` with this exact structure:

```
# API & Service Communication Contracts

A brief introduction (1-2 sentences) summarizing the API surface and communication patterns found.

## Service Catalog

[Table: Service | Port | Category | Purpose]

## API Endpoints Inventory

[Table: Service | Method | Path | Request Type | Response Type]

## Management & Observability Endpoints

[Table: Service | Endpoint | Custom Metrics (if any)]

## DTOs & Contracts

[Description of gateway-level DTOs vs service-level entities, immutability, serialization]

## Communication Patterns

[Description of sync/async patterns, gateway aggregation/composition logic, circuit breaker/retry policies with timeout values, service discovery, startup dependency chain, and security posture (authentication/authorization/TLS — or explicit statement that none is configured)]

## Service Technology Matrix

[Table: Service | Web | Data Access | Discovery | Gateway | Actuator | Cache | Metrics]

## Service Communication Sequence

< Mermaid sequenceDiagram here >
```

## Scaling Rules

- If the project has **more than 30 endpoints**, group by service/controller and show representative endpoints per group
- Keep the sequence diagram under **40 participants and messages** to ensure readability and GitHub rendering compatibility
- For multi-module projects, focus on inter-module communication in the sequence diagram and list all endpoints in the table
- Aggregate similar endpoints (e.g., CRUD operations on the same resource) into one table row if needed for brevity
- For the service technology matrix, use checkmarks or short labels; omit columns where no service uses the capability

## Common failure patterns observed in past runs

Each row below is something the model actually produced that crashed the diagram. Use the ✅ form.

| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed |
|---|---|---|
| `participant API` (no alias) | `participant API as "API"` | Bare participants with later spaces in usage break |
| `participant API as "REST API\n(SubsonicController)"` | `participant API as "REST API (SubsonicController)"` | Literal `\n` in alias |
| `participant API as "REST API: port 8080"` | `participant API as "REST API (port 8080)"` | `:` in alias collides with message delimiter |
| `Note over Client,API: First fact\nSecond fact` | Two consecutive `Note over Client,API: ...` lines | `\n` in note text |
| `alt happy path` ... missing `end` | `alt happy path` ... `end` | Unclosed block |
| `participant Svc as Order Service` (no quotes) | `participant Svc as "Order Service"` | Multi-word alias must be quoted |

## Error Handling

- **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.`
- **No API endpoints found**: Output: `> ERROR: No recognized API endpoints found at workspace-path. Verify the path is correct.`
- **Insufficient info**: Generate a best-effort document from available data. Add a note: `> Note: Some endpoints or communication patterns could not be fully identified.`

## Success Criteria

- Service catalog table lists all discovered services with ports, categories, and purposes
- API endpoints table lists all discovered endpoints with HTTP method, path, and types
- Management/observability endpoints are cataloged with custom metric names
- Gateway aggregation/composition patterns are documented with fallback behavior
- Service technology matrix shows per-service capabilities
- Communication patterns section describes sync/async patterns, resilience policies, and security posture (authentication, authorization, TLS — explicitly stating if none is configured)
- Mermaid sequence diagram renders correctly showing primary request flow with aggregation and fallback
- The ```mermaid block is preceded by the `<!-- mermaid-checked: ... -->` attestation comment
- File saved to `.github/modernize/assessment/engines/facts/api-service-contracts.md`