HTTP

Methods

HTTP defines a standard set of methods (verbs) with their own semantics so that we handle similar situations in the same way, removing unnecessary variation.

These methods are described in detail in HTTP Methods and are summarized in the table below. Resource archetypes describes when to use which methods for each resource type.

Rule: Use appropriate HTTP method [meth-http]

The HTTP methods SHOULD be used that are appropriate for the type of action performed on the resource.

The table below lists the usages of HTTP methods for each resource archetype. Combinations explicitly excluded ( -) SHOULD NOT be used.

The recently introduced HTTP method QUERY is not yet widely supported and SHOULD NOT be used.

Method Document Collection Controller Request body Response body

GET

consult

search

idempotent actions without side effects

Empty

Resource(s)

POST

operations when input is sensitive

create document

action with side effects or requiring request body

Representation of the created resource or controller info

Optional for resource creation. Depends on use case.

PUT

full update

-

-

Representation of the updated resource

Optional

PATCH

partial update

-

-

Fields of the resource to update

Optional

DELETE

remove

remove selection of items

-

Empty

Optional

HEAD

X

X

X

Empty

Empty

OPTIONS

X

X

X

Empty

Optional

Status Codes

HTTP defines a standard set of response status codes. They are described in detail in HTTP Status Codes and are summarized in the table below. The Resource archetypes chapter describes the most common status codes to use for operations on each resource type.

Rule: Use appropriate HTTP status codes [stat-codes]

The HTTP response status code SHOULD be returned that best describes the outcome of the treatment of the request.

The table below list most common combinations of a status code for each HTTP method, though may not be exhaustive. Combinations explicitly excluded ( -) SHOULD NOT be used.

Code GET HEAD PUT POST PATCH DELETE OPTIONS

200 OK

X

X

X

X (controller only)

X

X

X

201 Created

-

-

X (creation only)

X

-

-

-

202 Accepted

-

-

-

X

-

-

X

204 No Content

-

X

X

X

X

X

-

301 Moved Permanently

X

X

X

X

X

X

X

303 See Other

X

X

X

X

X

X

X

304 Not Modified

X

X

-

-

-

-

-

307 Temporary Redirect

X

X

X

X

X

X

X

400 Bad Request

X

X

X

X

X

X

X

401 Unauthorized

X

X

X

X

X

X

X

403 Forbidden

X

X

X

X

X

X

X

404 Not Found

X

X

X

X

X

X

X

405 Method Not Allowed

X

X

X

X

X

X

-

406 Not Acceptable

X

X

X

X

X

X

X

409 Conflict

-

-

X

X

X

X

-

412 Precondition Failed

-

-

X

X

X

X

-

413 Payload Too Large

-

-

X

X

X

-

-

415 Unsupported Media Type

X

X

X

X

X

X

X

429 Too Many Requests

X

X

X

X

X

X

X

500 Internal Server Error

X

X

X

X

X

X

X

502 Bad Gateway

X

X

X

X

X

X

X

503 Service Unavailable

X

X

X

X

X

X

X

Message body

The message body or content of an HTTP request or response is the data that is being transferred. The message body is optional and may be empty.

The HTTP protocol supports content negotiation for media types of the response.

Rule: Content negotiation [cnt-negot]

REST clients SHOULD specify the media type(s) that is(/are) acceptable for the response in the Accept HTTP header.

A REST response or request with message body MUST include the Content-Type HTTP header to indicate the media type of the HTTP body.

Status code 406 MUST be used to indicate that the requested media type could not be provided.

Status code 415 MUST be used to indicate an unsupported media type in the request body.

If a resource supports multiple content types through negotiation, the response header Vary: Accept MUST be added to avoid undesired cache hits (also see Caching).

Example 1. Content negotiation

Request HTTP headers:

Accept: image/jpeg, image/png

Response HTTP headers:

Content-Type: image/png
Vary: Accept

JSON

The primary media type for REST APIs to support is JSON (Javascript Object Notation). The choice for JSON is particularly useful to supporting JavaScript clients.

XML

On specific client request, a REST service can expose XML messages defined by XML Schema.

Content-Type: application/xml;charset=UTF-8

Always stick to UTF-8 encoding and specify the charset in the Content-Type HTTP header.

It is not recommended to implement both JSON / XML in each REST service. It would require to define and implement two representations of the same data. Automatic conversion between the two standards will almost never give a satisfying result.

Media types in OpenAPI

Message body media types can be specified in an OpenAPI description.

For JSON, the media type specified in OpenAPI should not contain a charset parameter, because this is known to lead to problems in some server software when treating requests without the parameter in the Accept header.

OpenAPI 3.0 allows to specify a different media type for each request or response format. Default media types across all operations cannot be specified.

Example 2. Specifying media types in OpenAPI
  /organizations/{enterpriseNumber}/logo:
    get:
      summary: Get the logo of the organization
      operationId: getLogo
      parameters:
        - in: query
          name: enterpriseNumber
          schema:
            $ref: "organization/identifier/v1/organization-identifier-v1.yaml#/components/schemas/EnterpriseNumber"
      responses:
        "200":
          description: successful operation
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        "404":
          description: Enterprise number was not found
          content:
            application/problem+json:
              schema:
                $ref: "problem/v1/#/components/schemas/InputValidationProblem"
        default:
          "$ref": "problem/v1/problem-v1.yaml#/components/responses/ProblemResponse"