Skip to content

RESTful

RESTful vs RPC == Resources and state transitions vs operations / method calls

HTTP methods describe semantics, not the endpoint implementation.

Methods

POST (Create)

  • Not idempotent by default. And should therefore only be called once.
  • Wird auch für Commands oder komplexe Queries verwendet, deren Parameter nicht sinnvoll in eine URL passen.
  • Kann einen Body haben.
  • Response
  • 201 => Created (mit Location Header)
  • 202 => Accepted for asynchronous processing

GET (Read)

  • Response
    • 200 => OK mit Body

PUT

  • Replace the resource representation at a known URI.
  • Idempotent => can be executed multiple times.
  • Hat einen Body.
  • Response
  • 200 => Updated representation
  • 204 => No Content
    => Wir müssen meistens auch das UI patchen (da(her) no content)

PATCH

  • Partial update.
  • Not guaranteed to be idempotent. set value can be idempotent, increment value is not.
  • Hat einen Body.
  • Response
  • 200 => Updated representation
  • 204 => No Content
    => Wir müssen meistens auch das UI patchen (da(her) no content)

DELETE

  • Idempotent => can be executed multiple times.
  • Response
    • 204 => No Content
      => Wir müssen meistens auch das UI patchen (da(her) no content)
    • Convention: An already missing resource also returns 204 because the desired state is reached.

OPTIONS

  • Describes the communication options for a resource, e.g. supported methods (Allow) or CORS.
  • Authorization is a separate concern.

StatusCodes

  • 2xx => Success
  • 4xx => Client error => Der Aufrufer kann durch Anpassung des Requests oder seiner Berechtigungen ein anderes Resultat erhalten.
  • 5xx => Server could not fulfill a valid request.
  • 500 => Unexpected server condition. Do not expose internal details.

Idempotent

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.

Idempotency concerns the intended server effect, not identical responses.

The HTTP specification states that following methods must be idempotent.

  • GET
  • PUT
  • DELETE

But following methods are not guaranteed to be idempotent.

  • POST
  • PATCH