API style Introduced in L3

REST

The dominant pattern for APIs over HTTP. Resources, methods, status codes — the vocabulary every backend speaks.

Mindmap

hover · click to navigate
this tech depends on / used by alternative Shipyard anchor
What it is

The plain-English version

REST (REpresentational State Transfer) is an architectural style for APIs over HTTP, formalized by Roy Fielding's 2000 dissertation. The mental model: resources (users, tasks) live at URLs, and you act on them with HTTP methods (GET to read, POST to create, PUT/PATCH to update, DELETE to remove). Most APIs you'll meet are "REST-ish" — pragmatic, not strict.

Why it exists

The problem it solves

REST won because it leverages HTTP's existing semantics (caching, status codes, methods) instead of inventing new ones. It's discoverable, debuggable with curl, and supported by every language. The downsides — over-fetching, multiple round-trips for related data — are why GraphQL and tRPC exist.

What it competes with

Alternatives

AlternativeTypeWhen it wins
GraphQLAPI styleAn API style where the client describes exactly what it wants in a single query. Solves REST's over-fetching, brings new operational complexity.
Where it shows up in Shipyard

Deep links

Vocabulary

The words you'll hear

Resource
A noun the API exposes. /users, /tasks/42.
Method
GET (read), POST (create), PUT (replace), PATCH (modify), DELETE (remove).
Status code
HTTP response code. 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error.
Idempotent
Same request, same effect. GET and PUT are idempotent; POST usually isn't.
HATEOAS
REST purist's grail: responses include links to next actions. Almost no real API does this.
OpenAPI / Swagger
A spec format for REST APIs. Generates docs and clients.
Prompting

Bad vs. good prompt for REST

✕ Bad prompt
make me a rest api
✓ Good prompt
Design a REST API for Tasklane. List the endpoints (method + path + body shape + response shape) for: list tasks, create task, get one task, update task, delete task, list comments on a task, add a comment. Use plural nouns. Return 201 with Location header on create. Include error response shape ({error: string, code: string}).

Why it works: Asks for the design as a list, not the implementation. Names the conventions (plurals, 201 + Location, error shape). The agent designs deliberately instead of guessing.

Pitfalls

What bites real teams

⚠ Verbs in URLs

/getUsers, /createTask — you've reinvented RPC. Use nouns and let the method be the verb.

⚠ Mixing PUT and PATCH

PUT replaces the whole resource; PATCH modifies fields. Pick one per endpoint and document it.

⚠ Returning HTTP 200 for errors

Anti-pattern: 200 OK { error: "not found" }. Use real status codes; clients depend on them.

References

Official docs only