- Home
- Skills
- APIs & Backend
- api and interface design
api and interface design
Design stable, predictable APIs and module boundaries using contract-first principles and robust idempotency patterns.
Free
Works with the AI Agents you already use
api and interface design
Example session with this skill installed
Design a REST API endpoint for creating a new project. Include the TypeScript interface, error handling, and idempotency logic.
- Read your context and instructions
- Compiled the api and interface
I have designed the project creation interface following contract-first principles and robust idempotency patterns.
Project Creation API Design
Interface Definition
// Input: Provided by the client
interface CreateProjectInput {
name: string;
description?: string;
visibility: 'PUBLIC' | 'PRIVATE';
teamId: string;
}
// Output: System-generated fields included
interface Project {
id: string & { readonly __brand: 'ProjectId' };
name: string;
description: string | null;
visibility: 'PUBLIC' | 'PRIVATE';
teamId: string;
createdAt: Date;
updatedAt: Date;
status: 'ACTIVE' | 'ARCHIVED';
}
API Endpoint & Error Handling
POST /api/projects
Headers: Idempotency-Key: <unique-uuid>
| Status Code | Error Code | Description |
|---|---|---|
| 201 Created | - | Project created successfully |
| 409 Conflict | IDEMPOTENCY_IN_PROGRESS | A request with this key is already being processed |
| 422 Unprocessable | VALIDATION_ERROR | Invalid input or key reused with different payload |
Idempotency Logic
The implementation must use an atomic claim to prevent race conditions:
try {
// Atomic insert to claim the key
await db.insert('idempotency_keys', {
key: idempotencyKey,
request_hash: hash(req.body),
status: 'started'
});
} catch (e) {
if (isUniqueViolation(e)) {
const existing = await db.find('idempotency_keys', idempotencyKey);
if (existing.request_hash !== hash(req.body)) {
return error(422, 'IDEMPOTENCY_KEY_REUSE_WITH_DIFFERENT_PAYLOAD');
}
return error(409, 'REQUEST_IN_PROGRESS');
}
throw e;
}
Next steps
- Implement the
CreateProjectSchemausing Zod for boundary validation. - Set a 24-hour TTL on the
idempotency_keystable. - Add the
ProjectIdbranded type to your global types file.
Connects securely to your tools. The creator never sees your data.
About this skill
Interfaces are the most expensive things to change once they are live. This skill helps you design stable, predictable APIs and module boundaries that resist breaking changes and prevent misuse. It provides concrete patterns for REST, GraphQL, and TypeScript interfaces, grounded in principles like Hyrum's Law and the One-Version Rule.
What it does
- Enforces contract-first design by requiring interface definitions before implementation to prevent tight coupling.
- Standardizes error semantics using structured machine-readable codes and consistent HTTP status mapping.
- Secures system boundaries by implementing validation at the edges (API routes, forms, and third-party responses) while trusting internal types.
- Hardens state-changing operations with rigorous idempotency patterns, including atomic key claims and payload guarding to prevent race conditions.
- Optimizes resource design through specific conventions for RESTful naming, pagination, and partial updates using PATCH.
How it works
- Define the contract by drafting TypeScript interfaces or API schemas for inputs and outputs.
- Apply design principles such as Hyrum's Law to ensure implementation details do not leak into the public surface.
- Audit against red flags like verbs in URLs, inconsistent error shapes, or non-atomic idempotency checks.
Frameworks & tools
TypeScript, REST, GraphQL, and Zod-style schema validation. Applicable to any backend or frontend stack where code modules interact.
Why this beats prompting it yourself
Generic prompts often ignore the nuance of Hyrum's Law or provide flawed idempotency logic that fails under race conditions. This skill provides production-grade patterns that specifically solve the diamond dependency problem and correlated retry storms.
Use cases
- Drafting a new microservice API that needs to support multiple frontend consumers.
- Refactoring a legacy module boundary to improve type safety and developer experience.
- Implementing safe payment or transaction processing using robust idempotency keys.
- Designing a public-facing SDK where backward compatibility is a hard requirement.
Known limitations
Does not provide implementation code for specific database drivers or web frameworks. Focuses on the interface layer and logic patterns rather than infrastructure setup.
Focuses on design patterns and logic rather than infrastructure code. Does not provide specific database drivers or framework-specific boilerplate.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
1 use
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 1 month ago
- Free with an Agensi account
Permissions
No special permissions declared or detected