HTTP methods and status codes in Rails APIs

Direct Answer

A Rails API should match HTTP methods to resource semantics—GET reads, POST creates or triggers processing, PUT/PATCH updates, and DELETE removes—and return a status that describes the outcome. Rails symbols such as :created, :no_content, :unprocessable_content, :unauthorized, and :forbidden map to standard HTTP codes.

Deep Dive & Architecture

A safe method is intended only to retrieve or inspect state. GET and HEAD are safe, so links, crawlers, prefetching, and caches may issue them without expecting a mutation. An endpoint that deletes a record on GET violates that contract even if the controller code works, because infrastructure and user agents are allowed to treat GET as observation.

Idempotent means repeating the same request has the same intended effect as making it once. PUT and DELETE are defined as idempotent, although each request may still create logs or update metrics. POST is not generally idempotent. Payment or job-start endpoints often add an idempotency key so a client can retry after a timeout without creating duplicate business work.

For creation, 201 says a new resource exists. Rails can render the representation and set location: article_url(article). A 202 response instead means processing was accepted but is not finished, which is appropriate when a background job owns completion. A 204 response means there is no content and Rails will drop a body supplied with a non-content status, so use 200 when the client needs an updated representation.

Client errors should remain specific without exposing sensitive data. A malformed JSON document can be 400. Failed authentication is 401, often with a WWW-Authenticate challenge. Refused permission is 403. A route or visible resource that does not exist is 404. Semantic validation errors can use 422 and a stable structure such as { errors: [{ field, code, message }] }.

The final design must be documented and tested as a contract. Request specs should assert allowed methods, exact status, important headers, and body shape for success and failure. Monitoring should group meaningful status families, while exception handling converts expected domain failures without turning programming defects into misleading 4xx responses.

Retries make these semantics practical. A client that loses a response needs to know whether repeating the operation is safe, idempotent, or protected by an idempotency key. Document that behaviour beside the status contract instead of leaving each client to guess.

Code Example

class Api::ArticlesController < ActionController::API
  def create
    article = Article.new(article_params)

    if article.save
      render json: article, status: :created, location: api_article_url(article)
    else
      render json: { errors: article.errors.to_hash }, status: :unprocessable_content
    end
  end

  private

  def article_params
    params.expect(article: [:title, :body])
  end
end

The success response identifies the new resource; validation failure remains a distinct client-visible outcome.

Common Mistakes & Pitfalls

Confusing authentication 401 with authorization 403 or returning a response body with 204.