Http Verbs

HTTP Verbs Explained: When to Use Each Method in Your API

APIs communicate intent using HTTP verbs (methods). Choosing the right verb makes your API more predictable, easier to use, and better aligned with web standards. This article explains the most common HTTP verbs, their semantics, safety and idempotency properties, and practical guidance for when to use each in your API.

Core HTTP verbs and their meanings

• GET — Retrieve a representation of a resource.

  • Semantics: Safe (should not change server state) and cacheable.
  • Use when: Returning data—lists, single resources, search results.
  • Example: GET /users/123 returns user 123.

• POST — Create a new resource or submit data to be processed.

  • Semantics: Not safe, not idempotent by default. Often used to create subordinate resources.
  • Use when: Creating a new resource when server assigns the ID, submitting forms, or performing operations that have side effects.
  • Example: POST /users with user data creates a new user.

• PUT — Replace a resource entirely (or create it at a known URI).

  • Semantics: Not safe, but idempotent (repeating the same PUT yields the same state).
  • Use when: Updating a resource with a full representation or upserting at a known URI.
  • Example: PUT /users/123 with full user object replaces user 123.

• PATCH — Apply partial modifications to a resource.

  • Semantics: Not safe; may or may not be idempotent depending on the patch semantics, but usually treated as non-idempotent unless defined otherwise.
  • Use when: Applying partial updates (change one or two fields) without sending the full resource. Use a clear patch format (e.g., JSON Patch, RFC 6902).
  • Example: PATCH /users/123 with { “email”: “[email protected]” } updates only the email.

• DELETE — Remove a resource.

  • Semantics: Not safe; typically idempotent (deleting an already-deleted resource returns the same result).
  • Use when: Removing a resource identified by URI. Consider soft delete patterns if you need recoverability.
  • Example: DELETE /users/123 deletes user 123.

Less‑common but useful verbs

• HEAD — Same as GET but returns only headers (no body). Useful for checking existence, metadata, or caching info.

  • Use when: Checking if a resource exists or validating cache/ETag without transferring the body.

• OPTIONS — Describe communication options for the target resource (CORS preflight uses this).

  • Use when: Advertising supported methods or handling CORS preflight requests.

• CONNECT and TRACE — Rare in typical REST APIs. CONNECT is for proxies/tunnels; TRACE echoes the request (used for diagnostics). Generally avoid exposing TRACE and carefully control CONNECT.

Idempotency, safety, and side effects — practical implications

• Safe methods (GET, HEAD) should not cause side effects. Clients and intermediaries can replay safe requests without worry.
• Idempotent methods (PUT, DELETE, sometimes PATCH) can be retried safely: applying the same request multiple times yields the same server state. This is important for clients under unreliable networks.
• Non-idempotent methods (POST) should not be retried automatically by clients or intermediaries without caution because they may create duplicates or repeat side effects.

Design tip: If an operation has side effects but you want retry safety, design it to be idempotent (e.g., accept a client-generated idempotency key with POST).

Practical patterns and examples

• Create a resource with server-generated ID:
  • POST /orders -> 201 Created, Location: /orders/789
• Create or replace a resource at a known URI:
  • PUT /orders/789 -> 200 or 201
• Partial update:
  • PATCH /orders/789 with JSON Patch -> 200 OK
• Retrieve resources:
  • GET /orders -> list; GET /orders/789 -> single
• Delete:
  • DELETE /orders/789 -> 204 No Content (or 200 with body)

Error handling and responses

• Use appropriate status codes:
  • 200 OK for successful GET/PUT/PATCH returning content.
  • 201 Created for successful POST that creates a resource.
  • 204 No Content for successful requests with no body (common for DELETE).
  • 400 Bad Request for malformed input.
  • 404 Not Found when resource doesn’t exist.
  • 409 Conflict for conflicting resource state (e.g., duplicate unique key).
  • 412 Precondition Failed when conditional headers (If-Match) fail.
• Leverage conditional requests (ETags, If-None-Match, If-Match) to prevent lost updates and to enable caching.

Best practices checklist

• Use GET for reads, POST for creates/processing, PUT for full replace/upsert, PATCH for partial updates, DELETE for deletes.
• Make write operations idempotent when possible or provide idempotency keys.
• Return appropriate HTTP status codes and Location header after creation.
• Use consistent URI design and plural nouns for collections (e.g., /users).
• Support pagination, filtering, and sorting for collection GETs.
• Provide clear API documentation including method semantics, expected status codes, and examples.
• Validate input and return helpful error payloads (machine-readable error objects).

Example quick reference table

*PATCH idempotency depends on patch semantics; design with care.

Closing notes

Follow HTTP method semantics to make your API intuitive, robust, and interoperable. Favor predictable behavior (safety and idempotency), clear status codes, and documented patterns so clients can interact reliably—especially under network failures.