# API Design Prover MCP > API Design Prover validates an API's entire contract before a single line of code is written. This MCP forces semantic HTTP verbs, explicit versioning strategies, and consistent response envelopes across every endpoint. It catches common design flaws like unbounded lists or mixed data shapes, guaranteeing that the resulting integration will be stable. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** api-design, rest-api, http-verbs, api-versioning, rfc-7807, api-pagination, contract-first, developer-experience ## Description Building APIs means making promises about how they work. Most AI-generated designs skip crucial steps: they use GET for creation requests; they don't version endpoints; and error messages look nothing alike across different routes. This MCP fixes that problem right at the design stage. It forces you to define every contract—how data looks on success, what happens when it fails, and how pagination works—before your team writes a single test case. You won't get vague suggestions about 'best practices.' Instead, you get an actionable verdict: Is this API ready? If not, the tool tells you exactly which protocol violation needs fixing, guiding you toward Stripe-grade reliability. When you connect to it via Vinkius, it acts as a strict gatekeeper for your entire service catalog. ## Tools ### validate_api_design Runs a thorough check on an entire API design, forcing adherence to semantic HTTP verbs, explicit versioning policies, consistent response envelopes, bounded pagination, and structured error contracts. ## Prompt Examples **Prompt:** ``` Let's create a GET endpoint /users/create to add a new user to our system. ``` **Response:** ``` Verdict: VERB_ABUSE. Using GET to add resources violates HTTP semantics. GET must be read-only (idempotent). Change the design to use POST /v1/users to create a new user resource. ``` **Prompt:** ``` API: User Management. Verbs: GET /v1/users (list), POST /v1/users (create), GET /v1/users/:id (details). Versioning: URL path prefix (/v1/). Response envelope: { data: T, meta: { total, page } }. Pagination: Limit-offset with default 20, max 100. Error contract: RFC 7807 JSON shape with type, title, status, and detail. ``` **Response:** ``` Verdict: API_PROVEN. Verbs are semantic, versioning is set via URL path, response shape is consistent, pagination enforces bounds, and errors follow RFC 7807. Design is clean and ready for implementation. ``` **Prompt:** ``` API: User Management. Verbs: GET /v1/users, POST /v1/users. Versioning: URL path. Response: raw array of users or raw user object on creation. Pagination: none, but we have a small dataset. Error contract: RFC 7807 format. ``` **Response:** ``` Verdict: SHAPE_INCONSISTENT. Your responses lack a unified envelope. Returning raw arrays on lists and raw objects on detail/creation routes prevents consistent client-side parsing. Standardize using an envelope structure first. ``` ## Capabilities ### Enforce Semantic Verbs It validates that each HTTP method (GET, POST, PUT, etc.) is used according to its technical purpose—for instance, only GET can be read-only and idempotent. ### Mandate Versioning Strategy The tool forces you to define how API versions are handled (URL paths or headers) and establishes a clear deprecation policy. ### Standardize Response Shapes It ensures every endpoint—whether listing data, creating a record, or reporting an error—returns the exact same JSON structure. ### Bound Data Lists It prevents endpoints from returning massive, unbounded datasets by requiring explicit pagination limits and cursors. ### Structure Error Handling The tool requires that all failures follow a standardized, machine-readable error contract (RFC 7807), eliminating vague status codes. ## Use Cases ### Migrating an old monolithic API The team is porting 50 endpoints from an old service. Instead of testing each one individually, the architect runs `validate_api_design` on the entire surface area. The tool instantly highlights which routes need version prefixes and which data types are inconsistent across the whole suite. ### Adding a new resource type A developer needs to add 'Invoices' endpoints. They prompt their agent, detailing POST/GET verbs and response shapes. The tool immediately flags that they used GET for creation, forcing them to switch to the proper POST verb mapping. ### Debugging client integration failures The QA team finds a sporadic bug where the mobile app crashes when fetching large user lists. Running `validate_api_design` reveals that pagination is unbounded, confirming the root cause and enforcing necessary limits. ## Benefits - Prevents 'Verb Abuse' (e.g., using GET for creation). The tool forces semantic verbs, guaranteeing that your endpoints behave predictably across caching layers and proxies. - Eliminates the risk of breaking changes. By enforcing versioning strategies, you can plan deprecation timelines years out, giving consumers time to migrate. - Guarantees consistent client parsing. It forces a unified JSON envelope for every single endpoint—success, failure, or list—so your SDKs never break due to shape chaos. - Stops memory leaks and timeouts. The tool mandates pagination bounds, ensuring that listing endpoints can't return 100K records in one call. - Makes error handling reliable. Instead of generic 'Internal Server Error' messages, the MCP forces structured, machine-readable error contracts (RFC 7807). - Saves review time. Architects use this to run a single contract validation pass instead of spending days manually checking documentation against implementation. ## How It Works The bottom line is that it turns abstract design ideas into concrete, verifiable technical specifications. 1. Provide the intended API surface and its functional requirements to your agent. 2. The MCP runs a series of five decision pivots, checking for verb semantics, versioning plans, response consistency, pagination bounds, and error contracts. 3. You receive a definitive verdict: either 'API_PROVEN' with all best practices met, or a specific violation report detailing exactly what needs correction. ## Frequently Asked Questions **How does the API Design Prover MCP handle different data types?** The tool forces response consistency, meaning every endpoint must return the same structure regardless of whether it's listing resources or detailing one. This prevents client-side parsing errors. **Does validate_api_design check business logic?** No. It only validates *how* your API is structured—the contracts, verbs, and formats. Business logic validation requires separate unit or integration tests. **What does the MCP do if I don't define a versioning strategy?** The tool will fail the `versioningDefined` pivot immediately. It forces you to specify whether versions change via URL paths, headers, or query params, ensuring future compatibility. **Can validate_api_design help with pagination limits?** Yes. The tool mandates that list endpoints must enforce bounds (limit/offset or cursor) and cannot return unlimited rows, preventing memory leaks on the client side. **How does running validate_api_design help define authentication requirements for my endpoints?** It doesn't enforce the auth mechanism, but it forces you to treat security as a contract requirement. You must specify which authenticated roles or scopes are required for read (GET) versus write (POST/PUT) actions. **Does validate_api_design check if I need rate limiting or performance boundaries?** Yes, it validates that your contract includes usage limits. You must define hard server-side bounds and recommend appropriate throttling headers (like X-RateLimit) to prevent service overload. **When I use validate_api_design, does the error contract cover tracing and specific failure codes?** Absolutely. The tool mandates adherence to RFC 7807 Problem Details. This requires more than a simple message; it demands structured fields like `type`, status code, and a unique correlation ID for debugging. **If I update an endpoint, how does validate_api_design help manage the transition or deprecation period?** It forces you to define a formal deprecation policy. When changing a field or removing an endpoint, the MCP requires specifying the sunset timeline and providing migration guidance for existing consumers. **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.