mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
745 lines
40 KiB
HTML
745 lines
40 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>api-rest-api-design</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/api-rest-api-design">
|
|
<link rel="alternate" type="text/markdown" href="/api-rest-api-design.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/api-rest-api-design.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>api-rest-api-design</h1><p class="lede">Designing RESTful APIs from scratch</p><h1>REST API Design</h1>
|
|
<p><strong>Scope</strong>: RESTful resource modeling, HTTP semantics, URL conventions, status codes <strong>Lines</strong>: ~280 <strong>Last Updated</strong>: 2025-10-18</p>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Activate this skill when:</p>
|
|
<ul><li>Designing RESTful APIs from scratch</li><li>Modeling resources and relationships</li><li>Choosing appropriate HTTP methods</li><li>Structuring API endpoints and URLs</li><li>Selecting correct HTTP status codes</li><li>Implementing API versioning strategies</li><li>Handling errors and validation</li><li>Optimizing for idempotency and caching</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>RESTful Principles</h3>
|
|
<p><strong>REST</strong> (Representational State Transfer): Architectural style for distributed systems.</p>
|
|
<p><strong>Key principles</strong>:</p>
|
|
<ul><li><strong>Stateless</strong>: Each request contains all needed information</li><li><strong>Resource-based</strong>: URLs identify resources (nouns, not verbs)</li><li><strong>HTTP methods</strong>: Use standard methods (GET, POST, PUT, DELETE)</li><li><strong>Uniform interface</strong>: Consistent patterns across API</li><li><strong>Self-descriptive</strong>: Responses include metadata (Content-Type, status codes)</li></ul>
|
|
<hr>
|
|
<h2>Resource Modeling</h2>
|
|
<h3>Resources are Nouns, Not Verbs</h3>
|
|
<p><strong>❌ Wrong</strong> (verb-based):</p>
|
|
<pre><code>POST /createUser
|
|
POST /getUserById
|
|
POST /updateUserEmail
|
|
POST /deleteUser</code></pre>
|
|
<p><strong>✅ Correct</strong> (resource-based):</p>
|
|
<pre><code>POST /users # Create user
|
|
GET /users/:id # Get user
|
|
PUT /users/:id # Update user
|
|
DELETE /users/:id # Delete user</code></pre>
|
|
<h3>Resource Naming Conventions</h3>
|
|
<p><strong>Use plural nouns</strong>:</p>
|
|
<pre><code>GET /users # ✅ Consistent plural
|
|
GET /user # ❌ Singular (inconsistent)</code></pre>
|
|
<p><strong>Lowercase with hyphens</strong> (not underscores or camelCase):</p>
|
|
<pre><code>GET /user-profiles # ✅ Kebab-case
|
|
GET /user_profiles # ❌ Snake_case (harder to read in URLs)
|
|
GET /userProfiles # ❌ camelCase (inconsistent)</code></pre>
|
|
<p><strong>Hierarchy for relationships</strong>:</p>
|
|
<pre><code>GET /users/:id/posts # User's posts
|
|
GET /users/:id/posts/:postId # Specific post by user
|
|
GET /posts/:id/comments # Comments on post</code></pre>
|
|
<p><strong>Collections vs Singular Resources</strong>:</p>
|
|
<pre><code>GET /users # Collection (returns array)
|
|
GET /users/42 # Singular resource (returns object)
|
|
GET /users/me # Special singular (current user)</code></pre>
|
|
<hr>
|
|
<h2>HTTP Method Semantics</h2>
|
|
<h3>GET - Retrieve Resources</h3>
|
|
<p><strong>Purpose</strong>: Fetch data without side effects</p>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li><strong>Safe</strong>: Doesn't modify state</li><li><strong>Idempotent</strong>: Multiple identical requests = same result</li><li><strong>Cacheable</strong>: Can be cached by intermediaries</li></ul>
|
|
<p><strong>Examples</strong>:</p>
|
|
<pre><code>GET /users # List all users
|
|
GET /users?page=2&limit=20 # Paginated list
|
|
GET /users/42 # Get user by ID
|
|
GET /users/42/posts # Get user's posts
|
|
GET /posts?author=alice # Filtered list</code></pre>
|
|
<p><strong>Response</strong>:</p>
|
|
<pre><code class="lang-json">// Single resource
|
|
{
|
|
"id": 42,
|
|
"email": "[email protected]",
|
|
"name": "Alice"
|
|
}
|
|
|
|
// Collection
|
|
{
|
|
"data": [
|
|
{"id": 1, "name": "Alice"},
|
|
{"id": 2, "name": "Bob"}
|
|
],
|
|
"meta": {
|
|
"total": 100,
|
|
"page": 1,
|
|
"per_page": 20
|
|
}
|
|
}</code></pre>
|
|
<h3>POST - Create Resources</h3>
|
|
<p><strong>Purpose</strong>: Create new resource or trigger action</p>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li><strong>Not safe</strong>: Modifies state</li><li><strong>Not idempotent</strong>: Multiple requests create multiple resources</li><li><strong>Not cacheable</strong></li></ul>
|
|
<p><strong>Examples</strong>:</p>
|
|
<pre><code>POST /users # Create new user
|
|
POST /posts # Create new post
|
|
POST /posts/42/publish # Action (publish post)</code></pre>
|
|
<p><strong>Request</strong>:</p>
|
|
<pre><code class="lang-json">POST /users
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"email": "[email protected]",
|
|
"name": "Alice",
|
|
"password": "secret123"
|
|
}</code></pre>
|
|
<p><strong>Response</strong> (201 Created):</p>
|
|
<pre><code class="lang-json">HTTP/1.1 201 Created
|
|
Location: /users/42
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 42,
|
|
"email": "[email protected]",
|
|
"name": "Alice",
|
|
"created_at": "2025-10-18T12:00:00Z"
|
|
}</code></pre>
|
|
<p><strong>Use POST for non-idempotent actions</strong>:</p>
|
|
<pre><code>POST /orders/42/payments # Process payment (not idempotent)
|
|
POST /users/42/send-email # Send email (side effect)</code></pre>
|
|
<h3>PUT - Replace Resource</h3>
|
|
<p><strong>Purpose</strong>: Replace entire resource (or create if doesn't exist)</p>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li><strong>Not safe</strong>: Modifies state</li><li><strong>Idempotent</strong>: Multiple identical requests = same result</li><li><strong>Not cacheable</strong></li></ul>
|
|
<p><strong>Examples</strong>:</p>
|
|
<pre><code>PUT /users/42 # Replace entire user
|
|
PUT /posts/123 # Replace entire post</code></pre>
|
|
<p><strong>Request</strong> (must include all fields):</p>
|
|
<pre><code class="lang-json">PUT /users/42
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"email": "[email protected]",
|
|
"name": "Alice Cooper", // Updated
|
|
"bio": "Developer" // All fields required
|
|
}</code></pre>
|
|
<p><strong>Response</strong> (200 OK):</p>
|
|
<pre><code class="lang-json">HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 42,
|
|
"email": "[email protected]",
|
|
"name": "Alice Cooper",
|
|
"bio": "Developer",
|
|
"updated_at": "2025-10-18T12:00:00Z"
|
|
}</code></pre>
|
|
<p><strong>PUT for upsert</strong> (create if not exists):</p>
|
|
<pre><code>PUT /users/[email protected] # Create or replace by email</code></pre>
|
|
<h3>PATCH - Partial Update</h3>
|
|
<p><strong>Purpose</strong>: Partially update resource (modify specific fields)</p>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li><strong>Not safe</strong>: Modifies state</li><li><strong>Not idempotent</strong> (depends on implementation)</li><li><strong>Not cacheable</strong></li></ul>
|
|
<p><strong>Examples</strong>:</p>
|
|
<pre><code>PATCH /users/42 # Update specific fields
|
|
PATCH /posts/123 # Update subset of post</code></pre>
|
|
<p><strong>Request</strong> (only modified fields):</p>
|
|
<pre><code class="lang-json">PATCH /users/42
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": "Alice Cooper" // Only update name
|
|
}</code></pre>
|
|
<p><strong>Response</strong> (200 OK):</p>
|
|
<pre><code class="lang-json">HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 42,
|
|
"email": "[email protected]",
|
|
"name": "Alice Cooper", // Updated
|
|
"bio": "Developer", // Unchanged
|
|
"updated_at": "2025-10-18T12:00:00Z"
|
|
}</code></pre>
|
|
<p><strong>PUT vs PATCH</strong>:</p>
|
|
<pre><code>PUT /users/42 # Replace entire user (all fields required)
|
|
PATCH /users/42 # Update specific fields (partial update)</code></pre>
|
|
<h3>DELETE - Remove Resource</h3>
|
|
<p><strong>Purpose</strong>: Delete resource</p>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li><strong>Not safe</strong>: Modifies state</li><li><strong>Idempotent</strong>: Deleting twice = same result (404 second time)</li><li><strong>Not cacheable</strong></li></ul>
|
|
<p><strong>Examples</strong>:</p>
|
|
<pre><code>DELETE /users/42 # Delete user
|
|
DELETE /posts/123 # Delete post</code></pre>
|
|
<p><strong>Response</strong> (204 No Content):</p>
|
|
<pre><code>HTTP/1.1 204 No Content</code></pre>
|
|
<p><strong>Or</strong> (200 OK with body):</p>
|
|
<pre><code class="lang-json">HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"message": "User deleted successfully",
|
|
"id": 42
|
|
}</code></pre>
|
|
<p><strong>Soft delete</strong> (use PATCH instead):</p>
|
|
<pre><code>PATCH /users/42
|
|
{"deleted_at": "2025-10-18T12:00:00Z"}</code></pre>
|
|
<hr>
|
|
<h2>HTTP Status Codes</h2>
|
|
<h3>Success Codes (2xx)</h3>
|
|
<p><strong>200 OK</strong>: Standard success response (GET, PUT, PATCH)</p>
|
|
<pre><code>GET /users/42 → 200 OK + user object
|
|
PUT /users/42 → 200 OK + updated user
|
|
PATCH /users/42 → 200 OK + updated user</code></pre>
|
|
<p><strong>201 Created</strong>: Resource created successfully (POST)</p>
|
|
<pre><code>POST /users → 201 Created + new user
|
|
Location: /users/42</code></pre>
|
|
<p><strong>204 No Content</strong>: Success with no response body (DELETE)</p>
|
|
<pre><code>DELETE /users/42 → 204 No Content</code></pre>
|
|
<p><strong>206 Partial Content</strong>: Partial resource (range requests)</p>
|
|
<pre><code>GET /videos/123
|
|
Range: bytes=0-1024 → 206 Partial Content</code></pre>
|
|
<h3>Redirection Codes (3xx)</h3>
|
|
<p><strong>301 Moved Permanently</strong>: Resource permanently moved</p>
|
|
<pre><code>GET /old-endpoint → 301 Moved Permanently
|
|
Location: /new-endpoint</code></pre>
|
|
<p><strong>304 Not Modified</strong>: Cached version is still valid</p>
|
|
<pre><code>GET /users/42
|
|
If-None-Match: "abc123" → 304 Not Modified</code></pre>
|
|
<h3>Client Error Codes (4xx)</h3>
|
|
<p><strong>400 Bad Request</strong>: Invalid request (validation failed)</p>
|
|
<pre><code class="lang-json">POST /users
|
|
{"email": "invalid"} → 400 Bad Request
|
|
{
|
|
"error": "Validation failed",
|
|
"details": {
|
|
"email": ["Must be valid email address"]
|
|
}
|
|
}</code></pre>
|
|
<p><strong>401 Unauthorized</strong>: Authentication required or failed</p>
|
|
<pre><code>GET /users/me → 401 Unauthorized
|
|
{
|
|
"error": "Authentication required",
|
|
"message": "Missing or invalid token"
|
|
}</code></pre>
|
|
<p><strong>403 Forbidden</strong>: Authenticated but not authorized</p>
|
|
<pre><code>DELETE /users/99 → 403 Forbidden
|
|
{
|
|
"error": "Forbidden",
|
|
"message": "You don't have permission to delete this user"
|
|
}</code></pre>
|
|
<p><strong>404 Not Found</strong>: Resource doesn't exist</p>
|
|
<pre><code>GET /users/99999 → 404 Not Found
|
|
{
|
|
"error": "Not found",
|
|
"message": "User not found"
|
|
}</code></pre>
|
|
<p><strong>409 Conflict</strong>: Request conflicts with current state</p>
|
|
<pre><code>POST /users
|
|
{"email": "[email protected]"} → 409 Conflict
|
|
{
|
|
"error": "Conflict",
|
|
"message": "User with this email already exists"
|
|
}</code></pre>
|
|
<p><strong>422 Unprocessable Entity</strong>: Valid syntax, but semantic errors</p>
|
|
<pre><code>POST /orders
|
|
{"product_id": 999} → 422 Unprocessable Entity
|
|
{
|
|
"error": "Unprocessable entity",
|
|
"message": "Product not found"
|
|
}</code></pre>
|
|
<p><strong>429 Too Many Requests</strong>: Rate limit exceeded</p>
|
|
<pre><code>GET /users → 429 Too Many Requests
|
|
Retry-After: 60
|
|
{
|
|
"error": "Rate limit exceeded",
|
|
"message": "Try again in 60 seconds"
|
|
}</code></pre>
|
|
<h3>Server Error Codes (5xx)</h3>
|
|
<p><strong>500 Internal Server Error</strong>: Unexpected server error</p>
|
|
<pre><code>GET /users → 500 Internal Server Error
|
|
{
|
|
"error": "Internal server error",
|
|
"message": "An unexpected error occurred"
|
|
}</code></pre>
|
|
<p><strong>502 Bad Gateway</strong>: Upstream server error (proxy/gateway)</p>
|
|
<pre><code>GET /users → 502 Bad Gateway
|
|
{
|
|
"error": "Bad gateway",
|
|
"message": "Upstream service unavailable"
|
|
}</code></pre>
|
|
<p><strong>503 Service Unavailable</strong>: Server temporarily unavailable</p>
|
|
<pre><code>GET /users → 503 Service Unavailable
|
|
Retry-After: 120
|
|
{
|
|
"error": "Service unavailable",
|
|
"message": "Server is under maintenance"
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>URL Structure Best Practices</h2>
|
|
<h3>Hierarchical Resource Relationships</h3>
|
|
<pre><code>GET /users/:userId/posts # User's posts
|
|
GET /users/:userId/posts/:postId # Specific post
|
|
GET /users/:userId/posts/:postId/comments # Post's comments</code></pre>
|
|
<p><strong>Limit nesting to 2-3 levels</strong>:</p>
|
|
<pre><code>✅ GET /posts/:postId/comments/:commentId
|
|
❌ GET /users/:userId/posts/:postId/comments/:commentId/replies/:replyId</code></pre>
|
|
<h3>Query Parameters for Filtering</h3>
|
|
<p><strong>Filtering</strong>:</p>
|
|
<pre><code>GET /posts?status=published&author=alice
|
|
GET /users?role=admin&verified=true</code></pre>
|
|
<p><strong>Sorting</strong>:</p>
|
|
<pre><code>GET /posts?sort=created_at:desc
|
|
GET /users?sort=-created_at # Descending (- prefix)
|
|
GET /products?sort=price:asc,name:asc # Multi-field</code></pre>
|
|
<p><strong>Pagination</strong>:</p>
|
|
<pre><code>GET /posts?page=2&limit=20 # Page-based
|
|
GET /posts?offset=20&limit=20 # Offset-based
|
|
GET /posts?cursor=abc123&limit=20 # Cursor-based (best for large datasets)</code></pre>
|
|
<p><strong>Field selection</strong> (sparse fieldsets):</p>
|
|
<pre><code>GET /users?fields=id,email,name # Only return specified fields
|
|
GET /posts?include=author,comments # Include related resources</code></pre>
|
|
<h3>Action Endpoints (Non-CRUD)</h3>
|
|
<p><strong>Use verbs for actions</strong> (not CRUD):</p>
|
|
<pre><code>POST /posts/:id/publish # Publish post
|
|
POST /users/:id/send-reset # Send password reset
|
|
POST /orders/:id/cancel # Cancel order
|
|
POST /carts/:id/checkout # Checkout cart</code></pre>
|
|
<p><strong>Alternative: Use status changes</strong>:</p>
|
|
<pre><code>PATCH /posts/:id # { "status": "published" }
|
|
PATCH /orders/:id # { "status": "cancelled" }</code></pre>
|
|
<hr>
|
|
<h2>Idempotency</h2>
|
|
<h3>Idempotent Methods</h3>
|
|
<p><strong>Safe + Idempotent</strong>: GET, HEAD, OPTIONS <strong>Idempotent (not safe)</strong>: PUT, DELETE</p>
|
|
<p><strong>GET</strong>: Multiple requests return same data</p>
|
|
<pre><code>GET /users/42 # Always returns same user (if unchanged)</code></pre>
|
|
<p><strong>PUT</strong>: Multiple identical requests = same result</p>
|
|
<pre><code>PUT /users/42
|
|
{"name": "Alice"} # Setting name to "Alice" multiple times = same result</code></pre>
|
|
<p><strong>DELETE</strong>: Multiple deletes = same result</p>
|
|
<pre><code>DELETE /users/42 # First: 204 No Content
|
|
DELETE /users/42 # Second: 404 Not Found (idempotent result)</code></pre>
|
|
<h3>Non-Idempotent Methods</h3>
|
|
<p><strong>POST</strong>: Multiple requests create multiple resources</p>
|
|
<pre><code>POST /orders # Creates new order each time
|
|
POST /payments # Processes payment each time (dangerous!)</code></pre>
|
|
<p><strong>Making POST idempotent</strong> (idempotency keys):</p>
|
|
<pre><code>POST /payments
|
|
Idempotency-Key: abc123
|
|
{"amount": 100}
|
|
|
|
# Second request with same key returns original response (no duplicate charge)
|
|
POST /payments
|
|
Idempotency-Key: abc123
|
|
{"amount": 100} # Returns 200 OK with original payment (no new charge)</code></pre>
|
|
<p><strong>Implementation</strong>:</p>
|
|
<pre><code class="lang-python">def create_payment(request):
|
|
idempotency_key = request.headers.get('Idempotency-Key')
|
|
|
|
# Check if already processed
|
|
existing = db.query("SELECT * FROM payments WHERE idempotency_key = %s", [idempotency_key])
|
|
if existing:
|
|
return 200, existing # Return original result
|
|
|
|
# Process new payment
|
|
payment = process_payment(request.body)
|
|
payment.idempotency_key = idempotency_key
|
|
db.save(payment)
|
|
|
|
return 201, payment</code></pre>
|
|
<hr>
|
|
<h2>REST Maturity Model (Richardson)</h2>
|
|
<h3>Level 0: The Swamp of POX (Plain Old XML)</h3>
|
|
<p><strong>Single endpoint, single method</strong>:</p>
|
|
<pre><code>POST /api
|
|
{"method": "getUser", "id": 42}
|
|
{"method": "createUser", "data": {...}}</code></pre>
|
|
<p>❌ Not RESTful</p>
|
|
<h3>Level 1: Resources</h3>
|
|
<p><strong>Multiple endpoints (resources)</strong>:</p>
|
|
<pre><code>GET /users/42
|
|
POST /users</code></pre>
|
|
<p>✅ Resource-based, but not using HTTP methods correctly</p>
|
|
<h3>Level 2: HTTP Verbs</h3>
|
|
<p><strong>Proper use of HTTP methods</strong>:</p>
|
|
<pre><code>GET /users/42 # Retrieve
|
|
POST /users # Create
|
|
PUT /users/42 # Update
|
|
DELETE /users/42 # Delete</code></pre>
|
|
<p>✅ RESTful, uses HTTP semantics</p>
|
|
<h3>Level 3: Hypermedia (HATEOAS)</h3>
|
|
<p><strong>Hypermedia As The Engine Of Application State</strong>:</p>
|
|
<p>Responses include links to related resources:</p>
|
|
<pre><code class="lang-json">GET /users/42
|
|
|
|
{
|
|
"id": 42,
|
|
"name": "Alice",
|
|
"email": "[email protected]",
|
|
"_links": {
|
|
"self": {"href": "/users/42"},
|
|
"posts": {"href": "/users/42/posts"},
|
|
"followers": {"href": "/users/42/followers"},
|
|
"edit": {"href": "/users/42", "method": "PUT"},
|
|
"delete": {"href": "/users/42", "method": "DELETE"}
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul><li>Self-documenting API</li><li>Clients discover actions dynamically</li><li>Server can change URLs without breaking clients</li></ul>
|
|
<p><strong>Trade-offs</strong>:</p>
|
|
<ul><li>Increased response size</li><li>More complex client implementation</li><li>Rarely fully implemented in practice</li></ul>
|
|
<hr>
|
|
<h2>Content Negotiation</h2>
|
|
<h3>Request Content Type</h3>
|
|
<p><strong>Client specifies format</strong>:</p>
|
|
<pre><code>POST /users
|
|
Content-Type: application/json
|
|
|
|
{"name": "Alice"}</code></pre>
|
|
<p><strong>Server validates</strong>:</p>
|
|
<pre><code>415 Unsupported Media Type (if Content-Type not supported)</code></pre>
|
|
<h3>Response Content Type</h3>
|
|
<p><strong>Client requests format</strong>:</p>
|
|
<pre><code>GET /users/42
|
|
Accept: application/json # Request JSON</code></pre>
|
|
<p><strong>Server responds</strong>:</p>
|
|
<pre><code>HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{"id": 42, "name": "Alice"}</code></pre>
|
|
<p><strong>Multiple formats supported</strong>:</p>
|
|
<pre><code>GET /users/42
|
|
Accept: application/xml # Request XML
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/xml
|
|
|
|
<user><id>42</id><name>Alice</name></user></code></pre>
|
|
<p><strong>Versioning via content type</strong>:</p>
|
|
<pre><code>Accept: application/vnd.myapi.v2+json</code></pre>
|
|
<hr>
|
|
<h2>API Versioning Strategies</h2>
|
|
<h3>URL Versioning (Most Common)</h3>
|
|
<pre><code>GET /v1/users/42
|
|
GET /v2/users/42</code></pre>
|
|
<p><strong>Pros</strong>: Simple, explicit, easy to route <strong>Cons</strong>: URL pollution, hard to migrate</p>
|
|
<h3>Header Versioning</h3>
|
|
<pre><code>GET /users/42
|
|
Accept: application/vnd.myapi.v2+json</code></pre>
|
|
<p><strong>Pros</strong>: Clean URLs, RESTful <strong>Cons</strong>: Harder to test (can't use browser directly)</p>
|
|
<h3>Query Parameter Versioning</h3>
|
|
<pre><code>GET /users/42?version=2</code></pre>
|
|
<p><strong>Pros</strong>: Simple, easy to test <strong>Cons</strong>: Less RESTful, query params should be for filtering</p>
|
|
<p><strong>Recommendation</strong>: URL versioning (<code>/v1/</code>, <code>/v2/</code>) for simplicity</p>
|
|
<hr>
|
|
<h2>HTTP Status Code Quick Reference</h2>
|
|
<p>| Code | Name | Use Case | |------|------|----------| | <strong>200</strong> | OK | Successful GET, PUT, PATCH | | <strong>201</strong> | Created | Successful POST (resource created) | | <strong>204</strong> | No Content | Successful DELETE or PUT with no response | | <strong>400</strong> | Bad Request | Validation error, malformed request | | <strong>401</strong> | Unauthorized | Authentication required or failed | | <strong>403</strong> | Forbidden | Authenticated but not authorized | | <strong>404</strong> | Not Found | Resource doesn't exist | | <strong>409</strong> | Conflict | Resource already exists, version conflict | | <strong>422</strong> | Unprocessable Entity | Valid syntax, semantic error | | <strong>429</strong> | Too Many Requests | Rate limit exceeded | | <strong>500</strong> | Internal Server Error | Unexpected server error | | <strong>502</strong> | Bad Gateway | Upstream service error | | <strong>503</strong> | Service Unavailable | Server under maintenance |</p>
|
|
<hr>
|
|
<h2>REST API Checklist</h2>
|
|
<pre><code>Resource Modeling:
|
|
[ ] Resources are nouns (not verbs)
|
|
[ ] Plural nouns for collections (/users, /posts)
|
|
[ ] Kebab-case for multi-word resources (/user-profiles)
|
|
[ ] Hierarchical relationships (/users/:id/posts)
|
|
|
|
HTTP Methods:
|
|
[ ] GET for retrieval (safe, idempotent)
|
|
[ ] POST for creation (non-idempotent)
|
|
[ ] PUT for full replacement (idempotent)
|
|
[ ] PATCH for partial updates
|
|
[ ] DELETE for removal (idempotent)
|
|
|
|
Status Codes:
|
|
[ ] 200 for successful GET/PUT/PATCH
|
|
[ ] 201 for successful POST (with Location header)
|
|
[ ] 204 for successful DELETE
|
|
[ ] 400 for validation errors
|
|
[ ] 401 for authentication errors
|
|
[ ] 403 for authorization errors
|
|
[ ] 404 for not found
|
|
[ ] 500 for server errors
|
|
|
|
Idempotency:
|
|
[ ] GET, PUT, DELETE are idempotent
|
|
[ ] POST uses idempotency keys for critical operations
|
|
[ ] PATCH operations are designed to be repeatable
|
|
|
|
Response Format:
|
|
[ ] Consistent error structure
|
|
[ ] Pagination metadata for collections
|
|
[ ] Timestamps in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
|
|
[ ] Snake_case or camelCase (consistent across API)
|
|
|
|
Security:
|
|
[ ] Authentication required for sensitive endpoints
|
|
[ ] Authorization checks before operations
|
|
[ ] Rate limiting implemented
|
|
[ ] Input validation on all endpoints</code></pre>
|
|
<hr>
|
|
<h2>Common REST Anti-Patterns</h2>
|
|
<p>❌ <strong>Verbs in URLs</strong>: <code>/getUser</code>, <code>/createPost</code> ✅ Use nouns + HTTP methods: <code>GET /users</code>, <code>POST /posts</code></p>
|
|
<p>❌ <strong>Using GET for actions</strong>: <code>GET /users/42/delete</code> ✅ Use DELETE: <code>DELETE /users/42</code></p>
|
|
<p>❌ <strong>Returning 200 for errors</strong>: <code>200 OK {"error": "User not found"}</code> ✅ Use proper status codes: <code>404 Not Found {"error": "User not found"}</code></p>
|
|
<p>❌ <strong>Inconsistent naming</strong>: <code>/users</code>, <code>/post</code>, <code>/getComments</code> ✅ Consistent plural nouns: <code>/users</code>, <code>/posts</code>, <code>/comments</code></p>
|
|
<p>❌ <strong>Deep nesting</strong>: <code>/orgs/:id/teams/:id/users/:id/posts/:id/comments/:id</code> ✅ Limit to 2-3 levels: <code>/posts/:id/comments</code> or <code>/comments?post_id=:id</code></p>
|
|
<p>❌ <strong>Ignoring idempotency</strong>: <code>POST /payments</code> (no idempotency key) ✅ Implement idempotency: <code>Idempotency-Key</code> header</p>
|
|
<p>❌ <strong>Exposing internal IDs</strong>: <code>/users/42</code> (auto-increment) ✅ Use UUIDs or obfuscated IDs: <code>/users/550e8400-e29b-41d4-a716-446655440000</code></p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>http-caching-strategies.md</code> - Cache headers, ETags, conditional requests</li><li><code>api-authentication.md</code> - JWT, OAuth2, API keys</li><li><code>api-rate-limiting.md</code> - Rate limiting strategies</li><li><code>graphql-vs-rest.md</code> - When to use GraphQL vs REST</li><li><code>openapi-documentation.md</code> - Documenting APIs with OpenAPI/Swagger</li></ul>
|
|
<hr>
|
|
<h2>Level 3: Resources</h2>
|
|
<p>This skill includes comprehensive Level 3 resources in the <code>/resources/</code> directory:</p>
|
|
<h3>Reference Material (<code>resources/REFERENCE.md</code>)</h3>
|
|
<p>Comprehensive 1,800+ line reference covering:</p>
|
|
<ul><li>REST principles (stateless, resource-based, uniform interface)</li><li>HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)</li><li>Status codes (proper usage for 2xx, 3xx, 4xx, 5xx)</li><li>URL design and resource naming</li><li>Request/response formats (JSON, content negotiation)</li><li>Pagination strategies (offset, cursor, page-based)</li><li>Filtering, sorting, and searching</li><li>Versioning strategies (URI, header, content negotiation)</li><li>Error handling and problem details (RFC 7807)</li><li>HATEOAS and hypermedia</li><li>Rate limiting and throttling</li><li>Caching (ETags, Cache-Control, conditional requests)</li><li>Authentication and authorization</li><li>CORS</li><li>API documentation (OpenAPI/Swagger)</li><li>Security best practices</li><li>Performance optimization</li><li>Testing strategies</li><li>Common patterns and anti-patterns</li></ul>
|
|
<h3>Executable Scripts (<code>resources/scripts/</code>)</h3>
|
|
<p><strong>validate_api.py</strong>:</p>
|
|
<ul><li>Validate REST API design against best practices</li><li>Check resource naming conventions, HTTP method usage, status codes</li><li>Validate response format consistency, security headers, rate limiting</li><li>Support for OpenAPI specs and custom formats</li><li>JSON output for CI/CD integration</li></ul>
|
|
<p><strong>generate_openapi.py</strong>:</p>
|
|
<ul><li>Generate OpenAPI specs from Python (FastAPI, Flask) or JavaScript (Express) code</li><li>Convert Swagger 2.0 to OpenAPI 3.0</li><li>Generate client code (Python, JavaScript, TypeScript) from OpenAPI specs</li><li>Automatic endpoint detection and schema generation</li></ul>
|
|
<p><strong>test_api.sh</strong>:</p>
|
|
<ul><li>Test REST API endpoints with various scenarios</li><li>CRUD operations, error handling, authentication</li><li>Pagination, filtering, sorting, caching</li><li>Rate limiting, CORS, content negotiation</li><li>Save responses and generate JSON reports</li></ul>
|
|
<h3>Complete Examples (<code>resources/examples/</code>)</h3>
|
|
<p><strong>python/fastapi_rest.py</strong>:</p>
|
|
<ul><li>Complete REST API with FastAPI</li><li>Resource-based endpoints, proper HTTP methods and status codes</li><li>Pagination, filtering, sorting</li><li>Authentication with Bearer tokens</li><li>Rate limiting, caching headers</li><li>Error handling with RFC 7807 format</li><li>Request validation with Pydantic</li></ul>
|
|
<p><strong>node/express_rest.js</strong>:</p>
|
|
<ul><li>Complete REST API with Express.js</li><li>Middleware for authentication, rate limiting, validation</li><li>Error handling and logging</li><li>Security headers with Helmet</li><li>Request ID tracking</li></ul>
|
|
<p><strong>openapi/petstore.yaml</strong>:</p>
|
|
<ul><li>Complete OpenAPI 3.0 specification</li><li>User management API example</li><li>Components, schemas, responses</li><li>Security schemes (Bearer auth)</li><li>Pagination, filtering, error responses</li></ul>
|
|
<p><strong>typescript/api_client.ts</strong>:</p>
|
|
<ul><li>Type-safe API client</li><li>Request/response interceptors</li><li>Retry logic and error handling</li><li>Caching with ETags</li><li>TypeScript interfaces for all models</li></ul>
|
|
<p><strong>curl/test_requests.sh</strong>:</p>
|
|
<ul><li>Comprehensive curl examples</li><li>CRUD operations, filtering, sorting, pagination</li><li>Error handling, authentication, conditional requests</li><li>CORS preflight, rate limiting, compression</li><li>Bulk operations and async patterns</li></ul>
|
|
<h3>Usage</h3>
|
|
<pre><code class="lang-bash"># Validate API design
|
|
./resources/scripts/validate_api.py openapi.json --type spec --json
|
|
|
|
# Generate OpenAPI from code
|
|
./resources/scripts/generate_openapi.py from-code api.py --framework fastapi -o openapi.json
|
|
|
|
# Test API endpoints
|
|
./resources/scripts/test_api.sh --url https://api.example.com --api-key TOKEN --verbose
|
|
|
|
# Run curl examples
|
|
cd resources/examples/curl && ./test_requests.sh
|
|
|
|
# Run FastAPI example
|
|
cd resources/examples/python && python fastapi_rest.py
|
|
|
|
# Run Express example
|
|
cd resources/examples/node && node express_rest.js</code></pre>
|
|
<hr>
|
|
<p><strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/api-rest-api-design.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |