# API Design Prover MCP for AI Agents AI Agent Connect

> API Design Prover forces your AI to design production-grade APIs that won't break your frontends or mobile apps. It catches common mistakes like using GET for creating resources, skipping versioning, or returning inconsistent data shapes. By enforcing industry-standard error structures and bounded pagination before you write a single line of code, it ensures your backend architecture is solid from day one.

## Overview
- **Category:** productivity
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_qg8XbvSmxEnaSpHzTf8C0mUG7OY2r5bZJfEFviZ0/ai-agent-connect
- **Tags:** api-design, rest-api, http-verbs, api-versioning, rfc-7807, api-pagination, contract-first, developer-experience

## Description

API Design Prover acts as a strict gatekeeper for your API contracts, ensuring your AI doesn't default to "junior developer" habits. Designing an API with an AI can feel like a shortcut until you actually try to connect a frontend to it. Most agents use GET for everything, ignore versioning entirely, and return different data structures for every route. This creates a mess where your mobile app crashes because a list is too long, or your CDN fails because an endpoint isn't idempotent. This Connector changes that by forcing the AI to commit to a specific versioning strategy, a unified response envelope, and proper HTTP verb usage before any code is generated. Instead of guessing what a response looks like, you get a guaranteed contract that follows industry standards like Stripe or GitHub. When you use this through the Vinkius catalog, you're moving from "hoping the API works" to having a proven blueprint. It catches the stuff that usually leads to late-night refactors, like missing pagination limits or non-standard error codes. You get a design that's actually ready for production. This means you stop wasting time on "shape chaos," where one route returns a raw array and the next returns a nested object. It also solves the "error void" problem where your frontend just gets a generic 500 message instead of a machine-readable error code. By validating these five pillars—semantics, versioning, consistency, pagination, and error contracts—you ensure that your API is scalable and maintainable from the first request.

## Tools

### validate_api_design
Checks your entire API surface against industry standards like RFC 7807 and proper HTTP verb semantics. It gives you a verdict and specific coaching to fix design flaws.

## Prompt Examples

**Prompt:** 
```
I need to design a route to let users update their profile pictures.
```

**Response:** 
```
To design a route for updating profile pictures, you should use a **PATCH** method. This allows you to update only the specific fields (like the image URL) without replacing the entire user object.

**Proposed Design:**
- **Endpoint:** `PATCH /v1/users/:id/avatar`
- **Request Body:** `{ "image_url": "string" }`
- **Success Response:**
  ```json
  {
    "data": { "image_url": "https://..." },
    "meta": { "updated_at": "2023-10-27T..." }
  }
  ```
- **Error Handling:** Returns **422 Unprocessable Entity** if the URL is invalid, following RFC 7807.
```

**Prompt:** 
```
Can you check if this API design is okay? I have GET /orders, POST /orders, and GET /orders/:id.
```

**Response:** 
```
I've analyzed your design. It has a **VERB_ABUSE** issue and **SHAPE_INCONSISTENT** errors.

| Endpoint | Verdict | Issue | Fix |
| :--- | :--- | :--- | :--- |
| `GET /orders` | **UNBOUNDED_RESPONSE** | No pagination limits. | Add `limit` and `offset` or a cursor. |
| `POST /orders` | **OK** | Correct verb usage. | |
| `GET /orders/:id` | **SHAPE_INCONSISTENT** | Returns raw object. | Wrap in a `{ data: T, meta: {} }` envelope. |

**Action Item:** Standardize all responses to use the same JSON envelope.
```

**Prompt:** 
```
How should I handle errors for a user who tries to sign up with an email that's already taken?
```

**Response:** 
```
For a duplicate email error, you should return a **409 Conflict** status code.

**RFC 7807 Structure:**
```json
{
  "type": "https://api.example.com/errors/duplicate-email",
  "title": "Email already in use",
  "status": 409,
  "detail": "The email address 'user@example.com' is already registered to another account.",
  "instance": "/v1/auth/signup"
}
```
This gives your frontend a clear machine-readable code to show a specific "Email taken" message.
```

## Capabilities

### Enforce correct HTTP verbs
Ensures your agent uses POST for creation and GET for reads to maintain cache integrity.

### Define clear versioning paths
Forces an explicit versioning strategy like URL prefixes to prevent breaking changes.

### Standardize response shapes
Guarantees every route returns a consistent JSON envelope for easier frontend parsing.

### Set hard pagination limits
Prevents mobile app crashes by enforcing maximum page sizes and cursor-based navigation.

### Mandate industry-standard error codes
Requires machine-readable error structures so your frontend can handle failures programmatically.

## Use Cases

### Fixing Verb Abuse
An agent suggests a GET request to delete a user. The tool detects the violation and forces a switch to a DELETE method.

### Preventing List Crashes
The mobile team complains about slow loads. Use validate_api_design to force a cursor-based pagination strategy on all lists.

### Standardizing Responses
Stop the frontend from needing custom parsers for every route by forcing a consistent JSON envelope across the board.

### Safe Versioning
Ensure the first schema change doesn't break the app by forcing a /v1/ prefix and a deprecation policy before coding.

## Benefits

- Stop breaking caches by using validate_api_design to enforce correct HTTP verbs for every endpoint.
- Avoid breaking changes with a forced versioning strategy that includes a clear deprecation timeline.
- Simplify frontend development by ensuring every route returns a unified JSON envelope.
- Prevent mobile app crashes by forcing bounded pagination and metadata on all collection endpoints.
- Reduce support tickets by mandating machine-readable RFC 7807 error structures for every failure.

## How It Works

The bottom line is you get a bulletproof API contract before you ever start coding.

1. Describe your API goals and routes to your agent
2. Run the validation check to find protocol violations
3. Get a corrected, production-ready design blueprint

## Frequently Asked Questions

**What does the API Design Prover actually do?**
It acts as a quality control gate for your API designs. It checks your routes against industry standards for verbs, versioning, and error handling before you write any code.

**Can this help me make my API more like Stripe's?**
Yes. It forces the AI to follow high-level patterns like consistent response envelopes and RFC 7807 error structures, which are hallmarks of top-tier APIs.

**Does this tool write the actual code for my endpoints?**
No, it validates the design blueprint. Once the design is proven correct, you can have your AI agent generate the implementation code.

**How does this help with mobile app crashes?**
It prevents crashes by forcing the AI to include bounded pagination on all list endpoints, ensuring your app never tries to load 10,000 rows at once.

**What is an RFC 7807 error contract?**
It is a standard way to return errors as machine-readable JSON. It helps your frontend show specific messages instead of just a generic 500 error.

**Will this tool help me with API versioning?**
Yes. It forces the AI to define a clear versioning strategy and a deprecation timeline so you don't accidentally break existing clients.

**Why does API Design Prover require RFC 7807?**
RFC 7807 (Problem Details) is the industry standard for HTTP API error shapes. It ensures that regardless of the endpoint or technology, client developers receive errors they can easily parse and handle.

**What versioning methods are supported?**
Path versioning (e.g., `/v1/users`), media type/header versioning, or query parameters. Path versioning is highly recommended due to its simple implementation and client compatibility.

**Does it enforce GraphQL standards?**
This tool is focused on REST APIs and HTTP resource design. For GraphQL or gRPC, you can adapt the pivots, but out-of-the-box checks validate HTTP status, HTTP verbs, and REST envelope consistency.