# Send Api Design to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "api-design", "name": "Api Design", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/shateily/api-design", "canonicalUrl": "https://clawhub.ai/shateily/api-design", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/api-design", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "api-design", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T00:27:15.822Z", "expiresAt": "2026-05-07T00:27:15.822Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design", "contentDisposition": "attachment; filename=\"api-design-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "api-design" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/api-design" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/api-design", "downloadUrl": "https://openagent3.xyz/downloads/api-design", "agentUrl": "https://openagent3.xyz/skills/api-design/agent", "manifestUrl": "https://openagent3.xyz/skills/api-design/agent.json", "briefUrl": "https://openagent3.xyz/skills/api-design/agent.md" } } ``` ## Documentation ### API Design Patterns Conventions and best practices for designing consistent, developer-friendly REST APIs. ### When to Activate Designing new API endpoints Reviewing existing API contracts Adding pagination, filtering, or sorting Implementing error handling for APIs Planning API versioning strategy Building public or partner-facing APIs ### URL Structure # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id # Sub-resources for relationships GET /api/v1/users/:id/orders POST /api/v1/users/:id/orders # Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login POST /api/v1/auth/refresh ### Naming Rules # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership # BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs /api/v1/users/123/getOrders # verb in nested resource ### Method Semantics MethodIdempotentSafeUse ForGETYesYesRetrieve resourcesPOSTNoNoCreate resources, trigger actionsPUTYesNoFull replacement of a resourcePATCHNo*NoPartial update of a resourceDELETEYesNoRemove a resource *PATCH can be made idempotent with proper implementation ### Status Code Reference # Success 200 OK — GET, PUT, PATCH (with response body) 201 Created — POST (include Location header) 204 No Content — DELETE, PUT (no response body) # Client Errors 400 Bad Request — Validation failure, malformed JSON 401 Unauthorized — Missing or invalid authentication 403 Forbidden — Authenticated but not authorized 404 Not Found — Resource doesn't exist 409 Conflict — Duplicate entry, state conflict 422 Unprocessable Entity — Semantically invalid (valid JSON, bad data) 429 Too Many Requests — Rate limit exceeded # Server Errors 500 Internal Server Error — Unexpected failure (never expose details) 502 Bad Gateway — Upstream service failed 503 Service Unavailable — Temporary overload, include Retry-After ### Common Mistakes # BAD: 200 for everything { "status": 200, "success": false, "error": "Not found" } # GOOD: Use HTTP status codes semantically HTTP/1.1 404 Not Found { "error": { "code": "not_found", "message": "User not found" } } # BAD: 500 for validation errors # GOOD: 400 or 422 with field-level details # BAD: 200 for created resources # GOOD: 201 with Location header HTTP/1.1 201 Created Location: /api/v1/users/abc-123 ### Success Response { "data": { "id": "abc-123", "email": "alice@example.com", "name": "Alice", "created_at": "2025-01-15T10:30:00Z" } } ### Collection Response (with Pagination) { "data": [ { "id": "abc-123", "name": "Alice" }, { "id": "def-456", "name": "Bob" } ], "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 }, "links": { "self": "/api/v1/users?page=1&per_page=20", "next": "/api/v1/users?page=2&per_page=20", "last": "/api/v1/users?page=8&per_page=20" } } ### Error Response { "error": { "code": "validation_error", "message": "Request validation failed", "details": [ { "field": "email", "message": "Must be a valid email address", "code": "invalid_format" }, { "field": "age", "message": "Must be between 0 and 150", "code": "out_of_range" } ] } } ### Response Envelope Variants // Option A: Envelope with data wrapper (recommended for public APIs) interface ApiResponse { data: T; meta?: PaginationMeta; links?: PaginationLinks; } interface ApiError { error: { code: string; message: string; details?: FieldError[]; }; } // Option B: Flat response (simpler, common for internal APIs) // Success: just return the resource directly // Error: return error object // Distinguish by HTTP status code ### Offset-Based (Simple) GET /api/v1/users?page=2&per_page=20 # Implementation SELECT * FROM users ORDER BY created_at DESC LIMIT 20 OFFSET 20; Pros: Easy to implement, supports "jump to page N" Cons: Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts ### Cursor-Based (Scalable) GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20 # Implementation SELECT * FROM users WHERE id > :cursor_id ORDER BY id ASC LIMIT 21; -- fetch one extra to determine has_next { "data": [...], "meta": { "has_next": true, "next_cursor": "eyJpZCI6MTQzfQ" } } Pros: Consistent performance regardless of position, stable with concurrent inserts Cons: Cannot jump to arbitrary page, cursor is opaque ### When to Use Which Use CasePagination TypeAdmin dashboards, small datasets (<10K)OffsetInfinite scroll, feeds, large datasetsCursorPublic APIsCursor (default) with offset (optional)Search resultsOffset (users expect page numbers) ### Filtering # Simple equality GET /api/v1/orders?status=active&customer_id=abc-123 # Comparison operators (use bracket notation) GET /api/v1/products?price[gte]=10&price[lte]=100 GET /api/v1/orders?created_at[after]=2025-01-01 # Multiple values (comma-separated) GET /api/v1/products?category=electronics,clothing # Nested fields (dot notation) GET /api/v1/orders?customer.country=US ### Sorting # Single field (prefix - for descending) GET /api/v1/products?sort=-created_at # Multiple fields (comma-separated) GET /api/v1/products?sort=-featured,price,-created_at ### Full-Text Search # Search query parameter GET /api/v1/products?q=wireless+headphones # Field-specific search GET /api/v1/users?email=alice ### Sparse Fieldsets # Return only specified fields (reduces payload) GET /api/v1/users?fields=id,name,email GET /api/v1/orders?fields=id,total,status&include=customer.name ### Token-Based Auth # Bearer token in Authorization header GET /api/v1/users Authorization: Bearer eyJhbGciOiJIUzI1NiIs... # API key (for server-to-server) GET /api/v1/data X-API-Key: sk_live_abc123 ### Authorization Patterns // Resource-level: check ownership app.get("/api/v1/orders/:id", async (req, res) => { const order = await Order.findById(req.params.id); if (!order) return res.status(404).json({ error: { code: "not_found" } }); if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } }); return res.json({ data: order }); }); // Role-based: check permissions app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => { await User.delete(req.params.id); return res.status(204).send(); }); ### Headers HTTP/1.1 200 OK X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640000000 # When exceeded HTTP/1.1 429 Too Many Requests Retry-After: 60 { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Try again in 60 seconds." } } ### Rate Limit Tiers TierLimitWindowUse CaseAnonymous30/minPer IPPublic endpointsAuthenticated100/minPer userStandard API accessPremium1000/minPer API keyPaid API plansInternal10000/minPer serviceService-to-service ### URL Path Versioning (Recommended) /api/v1/users /api/v2/users Pros: Explicit, easy to route, cacheable Cons: URL changes between versions ### Header Versioning GET /api/users Accept: application/vnd.myapp.v2+json Pros: Clean URLs Cons: Harder to test, easy to forget ### Versioning Strategy 1. Start with /api/v1/ — don't version until you need to 2. Maintain at most 2 active versions (current + previous) 3. Deprecation timeline: - Announce deprecation (6 months notice for public APIs) - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT - Return 410 Gone after sunset date 4. Non-breaking changes don't need a new version: - Adding new fields to responses - Adding new optional query parameters - Adding new endpoints 5. Breaking changes require a new version: - Removing or renaming fields - Changing field types - Changing URL structure - Changing authentication method ### TypeScript (Next.js API Route) import { z } from "zod"; import { NextRequest, NextResponse } from "next/server"; const createUserSchema = z.object({ email: z.string().email(), name: z.string().min(1).max(100), }); export async function POST(req: NextRequest) { const body = await req.json(); const parsed = createUserSchema.safeParse(body); if (!parsed.success) { return NextResponse.json({ error: { code: "validation_error", message: "Request validation failed", details: parsed.error.issues.map(i => ({ field: i.path.join("."), message: i.message, code: i.code, })), }, }, { status: 422 }); } const user = await createUser(parsed.data); return NextResponse.json( { data: user }, { status: 201, headers: { Location: \`/api/v1/users/${user.id}\` }, }, ); } ### Python (Django REST Framework) from rest_framework import serializers, viewsets, status from rest_framework.response import Response class CreateUserSerializer(serializers.Serializer): email = serializers.EmailField() name = serializers.CharField(max_length=100) class UserSerializer(serializers.ModelSerializer): class Meta: model = User fields = ["id", "email", "name", "created_at"] class UserViewSet(viewsets.ModelViewSet): serializer_class = UserSerializer permission_classes = [IsAuthenticated] def get_serializer_class(self): if self.action == "create": return CreateUserSerializer return UserSerializer def create(self, request): serializer = CreateUserSerializer(data=request.data) serializer.is_valid(raise_exception=True) user = UserService.create(**serializer.validated_data) return Response( {"data": UserSerializer(user).data}, status=status.HTTP_201_CREATED, headers={"Location": f"/api/v1/users/{user.id}"}, ) ### Go (net/http) func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) { var req CreateUserRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body") return } if err := req.Validate(); err != nil { writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error()) return } user, err := h.service.Create(r.Context(), req) if err != nil { switch { case errors.Is(err, domain.ErrEmailTaken): writeError(w, http.StatusConflict, "email_taken", "Email already registered") default: writeError(w, http.StatusInternalServerError, "internal_error", "Internal error") } return } w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID)) writeJSON(w, http.StatusCreated, map[string]any{"data": user}) } ### API Design Checklist Before shipping a new endpoint: Resource URL follows naming conventions (plural, kebab-case, no verbs) Correct HTTP method used (GET for reads, POST for creates, etc.) Appropriate status codes returned (not 200 for everything) Input validated with schema (Zod, Pydantic, Bean Validation) Error responses follow standard format with codes and messages Pagination implemented for list endpoints (cursor or offset) Authentication required (or explicitly marked as public) Authorization checked (user can only access their own resources) Rate limiting configured Response does not leak internal details (stack traces, SQL errors) Consistent naming with existing endpoints (camelCase vs snake_case) Documented (OpenAPI/Swagger spec updated) ## Trust - Source: tencent - Verification: Indexed source record - Publisher: shateily - Version: 1.0.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-30T00:27:15.822Z - Expires at: 2026-05-07T00:27:15.822Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/api-design) - [Send to Agent page](https://openagent3.xyz/skills/api-design/agent) - [JSON manifest](https://openagent3.xyz/skills/api-design/agent.json) - [Markdown brief](https://openagent3.xyz/skills/api-design/agent.md) - [Download page](https://openagent3.xyz/downloads/api-design)