1. HTTP Protocol

  • Request vs Response

  • URI vs URL

  • HTTP vs HTTPS

  • HTTP/1.1 vs HTTP/2.0

  • Methods

  • Statuses

  • Headers

1.1. HTTP Methods

Table 1.16. HTTP Methods

Method

Function

Description

GET

Read

Requests using GET should only retrieve data and should have no other effect.

POST

Create

The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI.

PUT

Update/Replace

The PUT method requests that the enclosed entity be stored under the supplied URI.

PATCH

Partial Update/Modify

The PATCH method applies partial modifications to a resource.

DELETE

Delete

The DELETE method deletes the specified resource.

HEAD

Show Headers

The HEAD method asks for a response identical to that of a GET request, but without the response body.

CONNECT

Connect

The CONNECT method converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy.

OPTIONS

Show HTTP Methods

The OPTIONS method returns the HTTP methods that the server supports for the specified URL.

TRACE

Show Trace

The TRACE method echoes the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.

1.2. HTTP Statuses

Table 1.17. HTTP Status Families

Code

Description

1XX

Informational

2XX

Successful

3XX

Redirection

4XX

Client Error

5XX

Server Error

1.2.1. 1xx Informational response

Table 1.18. HTTP Statuses 1xx Informational response

Code

Status

Description

100

Continue

101

Switching Protocols

102

Processing (WebDAV)

103

Early Hints

1.2.2. 2xx Success

Table 1.19. HTTP Statuses 2xx Success

Code

Status

Description

200

OK

201

Created

202

Accepted

203

Non-Authoritative Information

204

No Content

205

Reset Content

206

Partial Content

207

Multi-Status (WebDAV)

208

Already Reported (WebDAV)

209

IM Used

1.2.3. 3xx Redirection

Table 1.20. HTTP Statuses 3xx Redirection

Code

Status

Description

300

Multiple Choices

301

Moved Permanently

302

Found (Previously ‘Moved temporarily’)

303

See Other

304

Not Modified

305

Use Proxy

306

Switch Proxy

307

Temporary Redirect

308

Permanent Redirect

1.2.4. 4xx Client errors

Table 1.21. HTTP Statuses 4xx Client errors

Code

Status

Description

400

Bad Request

401

Unauthorized

402

Payment Required

403

Forbidden

404

Not Found

405

Method Not Allowed

406

Not Acceptable

407

Proxy Authentication Required

408

Request Timeout

409

Conflict

410

Gone

411

Length Required

412

Precondition Failed

413

Payload Too Large

414

URI Too Long

415

Unsupported Media Type

416

Range Not Satisfiable

417

Expectation Failed

418

I’m a teapot

This code was defined in 1998 as one of the traditional IETF April Fools’ jokes, in RFC 2324

421

Misdirected Request

422

Unprocessable Entity (WebDAV)

423

Locked (WebDAV)

424

Failed Dependency (WebDAV)

426

Upgrade Required

428

Precondition Required

429

Too Many Requests

431

Request Header Fields Too Large

451

Unavailable For Legal Reasons

1.2.5. 5xx Server errors

Table 1.22. HTTP Statuses 5xx Server errors

Code

Status

Description

500

Internal Server Error

501

Not Implemented

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

505

HTTP Version Not Supported

506

Variant Also Negotiates

507

Insufficient Storage (WebDAV)

508

Loop Detected (WebDAV)

510

Not Extended

511

Network Authentication Required

1.3. HTTP Headers

1.3.1. HTTP Request Headers

Table 1.23. HTTP Request Headers

Header

Description

Accept

Accept-Charset

Accept-Encoding

Accept-Language

Authorization

Cache-Control

Content-Length

Content-Type

Cookie

Date

Host

Origin

Pragma

Referer

User-Agent

DNT

X-Forwarded-For

X-Csrf-Token

1.3.2. HTTP Response Headers

Table 1.24. HTTP Response Headers

Header

Description

Access-Control-Allow-Origin

Access-Control-Allow-Methods

Allow

Cache-Control

Content-Disposition

Content-Encoding

Content-Language

Content-Length

Content-Type

Date

ETag

Expires

Last-Modified

Location

Pragma

Server

Set-Cookie

WWW-Authenticate

X-Frame-Options

Refresh

Status

1.4. MIME types

1.4.1. General structure

type/subtype
Table 1.25. Types

MIME type

Description

text

Represents any document that contains text and is theoretically human readable

image

Represents any kind of images. Videos are not included, though animated images (like animated gif) are described with an image type

audio

Represents any kind of audio files

video

Represents any kind of video files

application

Represents any kind of binary data

1.4.2. Text Types

Table 1.26. Text Types

MIME type

Description

text/plain

text/html

text/css

1.4.3. Application Types

Table 1.27. Application Types

MIME type

Description

application/json

application/javascript

application/ecmascript

application/octet-stream

As it really means unknown binary

application/pkcs12

application/vnd.mspowerpoint

application/xhtml+xml

application/xml

application/pdf

application/ogg

An audio or video file using the OGG container format. Theora is the usual video codec used within it; Vorbis is the usual audio codec

application/*

1.4.4. Multipart Types

Table 1.28. Multipart Types

MIME type

Description

multipart/form-data

multipart/byteranges

1.4.5. Image Types

Table 1.29. Image types

MIME type

Description

image/gif

GIF images (lossless compression, superseded by PNG)

image/jpeg

JPEG images

image/png

PNG images

image/svg+xml

SVG images (vector images)

image/x-icon

Windows icons

image/bmp

image/webp

image/vnd.microsoft.icon

1.4.6. Audio Types

Table 1.30. Audio Types

MIME type

Description

audio/wave

audio/wav

audio/x-wav

audio/x-pn-wav

An audio file in the WAVE container format. The PCM audio codec (WAVE codec ‘1’) is often supported, but other codecs have more limited support (if any)

audio/webm

An audio file in the WebM container format. Vorbis and Opus are the most common audio codecs

audio/ogg

An audio file in the OGG container format. Vorbis is the most common audio codec used in such a container

audio/midi

audio/mpeg

audio/*

1.4.7. Video Types

Table 1.31. Video Types

MIME type

Description

video/mp4

video/webm

video/ogg

video/webm

A video file, possibly with audio, in the WebM container format. VP8 and VP9 are the most common video codecs used within it; Vorbis and Opus the most common audio codecs

video/ogg

A video file, possibly with audio, in the OGG container format. Theora is the usual video codec used within it; Vorbis is the usual audio codec

1.5. API Versioning

1.5.1. Good Engineering Practices

  • Always version API

  • Have stable API!

  • Do not use plural in resources

  • Use HTTP Statuses

  • Use HTTP Methods

1.5.2. How to version API?

  • Semantic versioning

  • Django versioning

  • API deprication policy

Table 1.32. How to version API?

Example

Description

/api/v2/user/10

API version as a part of URL

X-API-VERSION: 2

Version as a custom header with X-... prefix

/user/10?api=v2

Version as a parameter to URL

Accept: application/vnd.api.v2

API version as a custom vendor prefix for Accept header

Accept: application/vnd.api.v2;q=0.9,application/vnd.api.v1;q=0.8

API version negotiation with weights using Accept header

apiv2.example.com

Subdomain