New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

REST API Conventions

by revfactory in revfactory/harness-100

REST API design conventions reference. An agent skill from revfactory/harness-100.

Apache-2.0Auto-check passedBackend & APIs

Install REST API Conventions

skills CLI
$ npx skills add revfactory/harness-100 --skill rest-api-conventions -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install revfactory/harness-100 rest-api-conventions --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .claude/skills && cp -r skills-src/en/18-api-designer/.claude/skills/rest-api-conventions .claude/skills/rest-api-conventions && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
rest-api-conventions
GitHub stars
1.3k
Token cost
~1.6k tokens
SKILL.md length
451 words
Files
1
Skills in repo
464
Repo updated
First seen
Licence
Apache-2.0

At a glance

REST API design conventions reference. An agent skill from revfactory/harness-100.

  • Designing RESTful APIs involving REST conventions
  • SKILL.md covers Target Agent, URL Naming Rules, HTTP Status Code Selection Guide and Pagination Patterns, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • HTTP status codes

What it does

REST API Conventions is an agent skill from revfactory/harness-100. REST API design conventions reference. An extension skill for api-architect that provides URL naming, HTTP method mapping, status code selection, pagination/filtering/sorting patterns, HATEOAS, and versioning strategies. Use when designing RESTful APIs involving 'REST conventions', 'URL design', 'HTTP status codes', 'pagination', 'API versioning', 'HATEOAS', etc. Note: GraphQL design and actual server implementation are outside the scope of this skill.

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering REST APIs. It works with GraphQL. The licence is Apache-2.0.

When your agent uses it

  • Designing RESTful APIs involving REST conventions
  • HTTP status codes

Example prompts

  • “REST conventions”
  • “URL design”
  • “HTTP status codes”
  • “/rest-api-conventions”

What it can do on your machine

Read from SKILL.md and the folder at commit 8e8d35c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

REST API Conventions loads about 1.6k tokens when it runs. Until then it costs about 119 tokens; SKILL.md has 451 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~119
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from revfactory/harness-100 at commit 8e8d35c, republished under its Apache-2.0 licence (© revfactory). 451 words, ~1,638 tokens.

Download SKILL.mdSave it as .claude/skills/rest-api-conventions/SKILL.md (or your agent's skills folder).
name
rest-api-conventions
description
REST API design conventions reference. An extension skill for api-architect that provides URL naming, HTTP method mapping, status code selection, pagination/filtering/sorting patterns, HATEOAS, and versioning strategies. Use when designing RESTful APIs involving 'REST conventions', 'URL design', 'HTTP status codes', 'pagination', 'API versioning', 'HATEOAS', etc. Note: GraphQL design and actual server implementation are outside the scope of this skill.

REST API Conventions — RESTful API Design Conventions Reference

A reference of naming rules, status codes, and pagination patterns used by the api-architect agent when designing REST APIs.

Target Agent

api-architect — Directly applies the conventions in this skill to API designs.

URL Naming Rules

Basic Principles
RuleCorrect ExampleIncorrect Example
Plural nouns/users/user, /getUsers
Lowercase kebab-case/user-profiles/userProfiles, /User_Profiles
No verbs (use methods for CRUD)POST /ordersPOST /createOrder
Hierarchical relationships/users/{id}/orders/getUserOrders
No trailing slash/users/users/
No file extensions/users (use Accept header)/users.json
Resource URL Patterns
OperationMethodURLExample
List retrievalGET/resourcesGET /products
Single retrievalGET/resources/{id}GET /products/123
CreatePOST/resourcesPOST /products
Full updatePUT/resources/{id}PUT /products/123
Partial updatePATCH/resources/{id}PATCH /products/123
DeleteDELETE/resources/{id}DELETE /products/123
Relationship Resources
GET  /users/{userId}/orders           -- User's order list
GET  /users/{userId}/orders/{orderId} -- User's specific order
POST /users/{userId}/orders           -- Create order for user
Non-CRUD Actions (RPC-Style Permitted)
POST /orders/{id}/cancel        -- Cancel order
POST /users/{id}/verify-email   -- Verify email
POST /reports/generate          -- Generate report
POST /cart/checkout             -- Proceed to checkout

HTTP Status Code Selection Guide

Success (2xx)
CodeMeaningWhen to Use
200OKGET, PUT, PATCH success
201CreatedPOST resource creation success (include Location header)
204No ContentDELETE success, no response body
Client Errors (4xx)
CodeMeaningWhen to Use
400Bad RequestMalformed request, validation failure
401UnauthorizedAuthentication required (missing/expired token)
403ForbiddenAuthenticated but not authorized
404Not FoundResource does not exist
405Method Not AllowedHTTP method not permitted
409ConflictResource conflict (duplicate creation, etc.)
422Unprocessable EntityFormat is correct but violates business rules
429Too Many RequestsRate limit exceeded
Server Errors (5xx)
CodeMeaningWhen to Use
500Internal Server ErrorUnexpected server error
502Bad GatewayUpstream service error
503Service UnavailableMaintenance/overload (include Retry-After header)

Pagination Patterns

Show full SKILL.md (186 more words)Show less
Offset-Based (Traditional)
GET /products?page=2&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
  • Pros: Simple implementation, random page access
  • Cons: Performance degradation with large datasets (OFFSET)
GET /products?cursor=eyJpZCI6MTIzfQ&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}
  • Pros: Excellent performance with large datasets, safe for real-time data
  • Cons: No total count or random page access
Selection Criteria
ScenarioRecommendation
Admin dashboard (page numbers needed)Offset
Infinite scrollCursor
Real-time feedCursor
1M+ recordsCursor

Filtering/Sorting/Search Patterns

Filtering
GET /products?category=electronics&price_min=10000&price_max=50000&status=active
Sorting
GET /products?sort=price&order=asc
GET /products?sort=-created_at,+name    (prefix style: - descending, + ascending)
GET /products?q=keyboard                (full-text search)
GET /products?name=keyboard             (specific field)
Field Selection (Sparse Fieldsets)
GET /products?fields=id,name,price      (only needed fields)

Error Response Standard Format

RFC 7807 (Problem Details)
json
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request data is invalid",
  "instance": "/products",
  "errors": [
    {
      "field": "price",
      "code": "INVALID_RANGE",
      "message": "Price must be greater than 0"
    }
  ]
}

Versioning Strategies

StrategyMethodProsCons
URL Path/v1/usersClear, simple routingURL changes
HeaderAccept: application/vnd.api+json;version=1Clean URLsHarder to debug
Query/users?version=1Can be optionalComplex caching

Recommended: URL Path (/v1/) — Most intuitive and widely adopted

Version Deprecation Policy
  • New version released -> Maintain old version for 12 months
  • Deprecation headers: Deprecation: true, Sunset: 2025-12-31
  • Provide migration guide

Response Envelope Pattern

Single Resource Response
json
{
  "data": { "id": 1, "name": "Product" },
  "meta": { "requestId": "abc-123" }
}
List Response
json
{
  "data": [{ "id": 1 }, { "id": 2 }],
  "pagination": { "page": 1, "limit": 20, "total": 150 },
  "meta": { "requestId": "abc-123" }
}

Idempotency

MethodIdempotentSafeDescription
GETYesYesReturns the same result
PUTYesNoSame data repeated yields the same result
DELETEYesNoRe-deleting an already deleted resource returns 404
PATCHNoNoCan make relative changes (counter++)
POSTNoNoMay create duplicates -> Idempotency-Key recommended

© revfactory, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in en/18-api-designer/.claude/skills/rest-api-conventions of revfactory/harness-100.

Open the folder on GitHubat commit 8e8d35c

Compare with similar skills

REST API Conventions next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

REST API Conventions compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
REST API Conventions this skillrevfactory/harness-1001.3k—~1.6kAutomated safety check: PassApache-2.0
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
Nodejs Backend Patternsever-works/ever-works15817 repos~4kAutomated safety check: PassAGPL-3.0
Use Yaakmountain-loop/yaak19k—~1.9kAutomated safety check: PassMIT
Backend Endpointqf-studio/navigator3541 repos~4.5kAutomated safety check: NotesMIT
API Auditbriiirussell/cybersecurity-skills412—~2.8kAutomated safety check: NotesMIT

Similar skills

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • Nodejs Backend Patterns

    ever-works/ever-works

    Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices.

    158 GitHub starsUsed in 17 repos~4k tokens
    Backend & APIsAuto-check passed

  • Use Yaak

    mountain-loop/yaak

    A skill your agent uses when the user mentions Yaak, a Yaak workspace, or the yaak command, or asks to call, hit, or smoke test HTTP/REST endpoints, save or organize API requests for reuse or manual…

    19k GitHub stars~1.9k tokensUpdated today
    Backend & APIsAuto-check passed

  • Backend Endpoint

    qf-studio/navigator

    Create REST/GraphQL API endpoint with validation, error handling, and tests.

    354 GitHub starsUsed in 1 repo~4.5k tokens
    Backend & APIsAuto-check: notes

  • API Audit

    briiirussell/cybersecurity-skills

    Audit REST, GraphQL, and RPC APIs against the OWASP API Security Top 10 (2023).

    412 GitHub stars~2.8k tokensUpdated 4 mo ago
    Backend & APIsAuto-check: notes

  • Data Client Schema

    reactive/data-client

    Model data with @data-client schemas (Entity, EntityMixin, Collection, Union, Query, Values, All, Invalidate, Lazy, Scalar) for atomic, consistent, referentially-equal async data via normalization…

    2k GitHub stars~2.3k tokensUpdated today
    Backend & APIsAuto-check passed

More from revfactory/harness-100

All 464 skills in this repo

  • Anti Bot Analyzer

    revfactory/harness-100

    A skill for analyzing website anti-bot defense mechanisms and developing legitimate evasion strategies.

    1.3k GitHub stars~1.1k tokensUpdated 6 mo ago
    Auto-check passed

  • API Error Design Patterns

    revfactory/harness-100

    Reference for designing how an API reports failures: structured error codes, response shapes, client-friendly messages, an error catalog and retry or fallback advice.

    1.3k GitHub stars~1.6k tokensUpdated 6 mo ago
    Auto-check passed

  • API Security Checklist

    revfactory/harness-100

    Walks a backend-dev agent through OWASP API Top 10 checks, authentication and authorization patterns, and defense code during API design.

    1.3k GitHub stars~1.7k tokensUpdated 6 mo ago
    Auto-check passed

  • Arg Parser Generator

    revfactory/harness-100

    Methodology for systematically designing and generating CLI tool argument parser structures.

    1.3k GitHub stars~1.2k tokensUpdated 6 mo ago
    Auto-check passed

  • Audience Segmentation

    revfactory/harness-100

    Audience segmentation skill used by the analyst and curator agents.

    1.3k GitHub stars~1.3k tokensUpdated 6 mo ago
    Auto-check passed

  • Audio Storytelling

    revfactory/harness-100

    Audio storytelling skill used by the podcast scriptwriter and show note editor.

    1.3k GitHub stars~1.6k tokensUpdated 6 mo ago
    Auto-check passed

Works with

Categories

Questions about REST API Conventions

What does REST API Conventions do?

REST API design conventions reference. An agent skill from revfactory/harness-100. REST API Conventions is an agent skill from revfactory/harness-100. REST API design conventions reference.

When should I use REST API Conventions?

REST API Conventions fits situations like: designing RESTful APIs involving REST conventions; HTTP status codes.

How do I install REST API Conventions in Claude Code?

Run `npx skills add revfactory/harness-100 --skill rest-api-conventions -a claude-code`. Or copy the skill folder (en/18-api-designer/.claude/skills/rest-api-conventions in revfactory/harness-100) into .claude/skills/rest-api-conventions in your project. Claude Code loads it when a task matches its description.

How do I install REST API Conventions in Codex?

Run `npx skills add revfactory/harness-100 --skill rest-api-conventions -a codex`. Or copy the skill folder (en/18-api-designer/.claude/skills/rest-api-conventions in revfactory/harness-100) into .agents/skills/rest-api-conventions in your project. Codex loads it when a task matches its description.

Can I use REST API Conventions in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add revfactory/harness-100 --skill rest-api-conventions -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/rest-api-conventions, .gemini/skills/rest-api-conventions, .github/skills/rest-api-conventions and .opencode/skills/rest-api-conventions in your project.

What does REST API Conventions need to run?

SKILL.md names no scripts, command-line tools or credentials: REST API Conventions is instructions for the agent only.

Does REST API Conventions access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is REST API Conventions safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does REST API Conventions use?

REST API Conventions is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does REST API Conventions use?

About 1.6k tokens (SKILL.md is roughly 6.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to REST API Conventions?

Skills that share tags, products or a category with REST API Conventions: API Designer (Jeffallan/claude-skills, 12k stars), Nodejs Backend Patterns (ever-works/ever-works, 158 stars), Use Yaak (mountain-loop/yaak, 19k stars) and Backend Endpoint (qf-studio/navigator, 354 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains REST API Conventions?

revfactory (a GitHub user) maintains it in revfactory/harness-100, which has 1,290 GitHub stars. The repository holds 464 skills in this directory. The repository was last updated on March 22, 2026.

Source: revfactory/harness-100 on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.