rest-api-conventions

A reference for designing HTTP/JSON REST APIs, which are web interfaces programs use to exchange data. It covers resource naming, methods, status codes, pagination, errors, and versioning.

In plain words
What is it for?
Designing or reviewing REST endpoints, request and response formats, pagination, error handling, and API versions.
Why use it?
It helps make APIs predictable for the developers and programs that consume them. Consistent conventions also make failures and future changes easier to handle.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/ikarusmk/aicortex/rest-api-conventions
Any agent
npx skills add IkarusMK/AIcortex --skill rest-api-conventions
Clone the repo
git clone --depth 1 https://github.com/IkarusMK/AIcortex

Made for: Claude Code, Codex.

Per session 26 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 392 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00026 $0.00392
Opus 5 $0.00013 $0.00196
Sonnet 5 $0.00005 $0.00078
Haiku 4.5 $0.00003 $0.00039

Measured 2d ago against content hash 166ac54ecf06, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

rest-api-conventions scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

examples/skills/rest-api-conventions/SKILL.md · 37 lines

What it actually says

REST API Conventions

When to use

Designing or reviewing an HTTP/JSON API.

Resources & methods

  • Nouns, plural: /orders, /orders/{id}/items. No verbs in paths.
  • GET read (safe, idempotent) · POST create · PUT/PATCH replace/update · DELETE remove. POST for non-CRUD actions: /orders/{id}/refund.

Status codes

200 ok · 201 created (+ Location) · 204 no content · 400 bad input · 401 unauthenticated · 403 forbidden · 404 not found · 409 conflict · 422 validation · 429 rate-limited · 5xx server. Don't return 200 with an error body.

Lists

  • Paginate everything that can grow: ?limit=&cursor= (cursor) or ?page=&per_page=.
  • Filtering/sorting via query params: ?status=open&sort=-created_at.
  • Return pagination metadata (total / next cursor) consistently.

Errors (one shape everywhere)

{ "error": { "code": "validation_error", "message": "…", "details": [ … ] } }

Also

  • Version at the edge: /v1/…. Don't break v1 in place.
  • Be consistent: same field casing, same date format (ISO 8601 UTC), same error shape.
  • Make writes idempotent where clients may retry (idempotency keys).
Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 37 lines · 26 tokens per session scan A 166ac54ecf06

Subscribe to this mod's changes

rest-api-conventions is a skill published in the GitHub repository IkarusMK/AIcortex (9 stars, last pushed 13d ago), licensed Apache-2.0. It adds 26 tokens to every session and 392 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

MCP Server Builder

Step-by-step guidance for creating a new MCP server with FastMCP or the TypeScript SDK — tool definitions, resource handlers, error responses, and usage examples.

Notysoty/openagentskills · 38 tokens

react-grab

Use when the user wants a hands-free loop where grabbing UI elements in the browser with React Grab feeds tasks to the agent automatically, with no copy-paste or manual handoff. Triggers: "watch react grab", "monitor my grabs", "auto-process react grab", "watch my clipboard for grabs". Not for a one-off paste of a…

aidenybai/react-grab · 86 tokens

fix-issues

Fix a batch of open GitHub issues end to end - one git worktree and one agent per issue (feature-dev for implementation, review-pr for review), individual PRs into develop, a release PR to main with a final multi-agent integration review, and optional tag/release/issue-comment publishing. Use when the user asks to…

kossakovsky/selfhost-ai · 80 tokens

lc-curate-context

Decide which files a task actually needs, record that as a reusable llm-context rule, verify it against the codebase - including the files your selection references but leaves out - and pack it for your own context, a chat, or a sub-agent you dispatch. Load when choosing what code to put in front of a model, packing…

cyberchitta/llm-context.py · 90 tokens

promote

GitHub 截流。在同领域项目(local coding agent ↔ IM / mobile / remote console)的 feature-request issue 下,自动发现→起草→自我批判→护栏→(按 posture)发布 pikiloom 回复,并记录+度量。话术统一来自 promo/pitch.md;可由 promo/orchestrate.md 无人值守驱动。.

xiaotonng/pikiloom · 84 tokens

bzdesignprompt

为前端或网页设计任务选择并下载合适的 DESIGN.md 模板。当用户需要网页设计模板、UI 风格参考、设计系统、落地页或前端界面设计时,浏览长亭百智云 UI 设计模板库,根据产品场景和视觉偏好匹配模板,并将完整 DESIGN.md 保存到项目中。.

chaitin/MonkeyCode · 79 tokens