rest-api-architect — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited rest-api-architect (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Cross-language conventions for HTTP/JSON REST APIs. Framework-agnostic. Pair with fastapi-architect or gin-architect for implementation. See STACK.md for the specs this skill is built on.
/v1/users, /v1/orders. Never verbs in URLs (/v1/createUser is wrong — the method is the verb)./v1/users/{user_id}, never as a query parameter./v1/orders/{order_id}/items. Beyond one level, use IDs and filter queries instead — deeper hierarchies turn brittle the moment relationships change./v1/orders/{id}/cancellation (PUT to create) instead of POST /v1/orders/{id}/cancel. The state change is what is created, not a verb on the parent.| Method | Purpose | Idempotent | Safe |
|---|---|---|---|
GET | Read | Yes | Yes (no side effects) |
POST | Create (server assigns ID) or action that doesn't fit elsewhere | No | No |
PUT | Replace entire resource (client supplies full state) | Yes | No |
PATCH | Partial update | No (unless body is itself idempotent — usually not) | No |
DELETE | Remove | Yes | No |
PUT with only some fields is a bug — that's PATCH's job./v1/payments/{id}/refunds (creates a refund). The resource is the action's outcome.Use the right code for the situation. The full table — every code, when to use it, the common confusions (401 vs 403, 404 vs 410, 422 vs 400) — is in STATUS_CODES.md.
One hard rule: never 200 OK for errors. Returning {"success": false, "error": ...} with a 200 status is wrong and breaks every HTTP-aware tool.
/v1/users, /v2/users. No header-based versioning, no query-param versioning.Deprecation and Sunset response headers (RFC 8594) before removing./v1/ from day one.Cursor pagination is stable under concurrent writes and O(1) per page; offset is O(N) and reads can shift between pages. Request/response shape + rules in PAYLOADS § 1.
?status=paid&customer_id=01J9.... Equality only by default — operator syntax (?price[gte]=100) is fine for richer endpoints but document each operator in OpenAPI.?sort=-created_at,name — comma-separated, prefix - for descending. Document allowed sort fields.?q=alice for free-text search across documented columns. Don't expose raw SQL LIKE patterns from clients.?fields=id,email,created_at to limit response payload — useful for list endpoints. Validate against the schema.Every error response uses application/problem+json. Canonical shape + rules in PAYLOADS § 2; structured 422 validation shape in PAYLOADS § 3.
Key rules:
Idempotency-Key mandatoryEvery POST and PATCH requires an Idempotency-Key header. Without it the server returns 400 Bad Request. The server caches the response keyed by (caller_id, method, path, key) for 24h and replays on retry; GET/PUT/DELETE are already idempotent by HTTP semantics and don't need it.
Full implementation reference — cache shape, TTL choice, concurrent-request handling, storage options, client guidance, common mistakes — in IDEMPOTENCY.md.
ETag + If-Match mandatoryEvery editable resource exposes an ETag on read. Every PUT and PATCH requires If-Match matching the current ETag, or returns 412 Precondition Failed. If-None-Match on GET enables 304 Not Modified caching for free.
Full implementation reference — where the ETag value comes from (default: monotonic version column), strong vs weak, the 412 retry flow, common mistakes — in CONCURRENCY.md.
Access-Control-Allow-Origin: * for authenticated endpoints.Strict-Transport-Security, X-Content-Type-Options: nosniff, Content-Security-Policy (if serving HTML), Referrer-Policy: no-referrer.Two patterns cover almost every API: in-house OAuth2 + JWT for single-service deployments, external IdP (Keycloak / Auth0 / Cognito / Entra) for multi-service, MFA, social login, or SSO/compliance needs. Full reference — Argon2id, HS256→RS256 switching, refresh-token rotation + reuse detection, JWKS verification with cached keys, mandatory aud/iss checks, when to switch A→B, per-endpoint authorization — in AUTH_PATTERNS.md.
Framework-specific implementation:
OAuth2PasswordBearer + pyjwt + argon2-cffigolang-jwt/jwt/v5 + argon2application/problem+json for errors regardless of Accept."2026-05-20T14:23:00Z" or "2026-05-20T14:23:00+00:00". Never Unix epoch numbers — they're ambiguous about units (seconds vs ms) and harder to log-grep."99.99") — JSON numbers are floats and lose precision."01j9x...-..."). UUID v7 by default (sortable, distributed) — matches sql-architect.PATCH. Document the distinction.private, no-store for authenticated user data; public, max-age=300 for genuinely public reference data (e.g. countries).304.Vary, intermediaries serve the wrong cached entry to a different user.429 and 503. Header reference in PAYLOADS § 4.openapi.snapshot.json on every PR; any change is reviewed./v1/openapi.json) and consumed by client-SDK generators, Postman collections, and API documentation tooling.Depends, gin.Context, middleware ordering) — see the framework architect skills.~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.