3. HTTP Protocol

  • Request vs Response
  • URI vs URL
  • HTTP vs HTTPS
  • HTTP/1.1 vs HTTP/2.0
  • Methods
  • Statuses
  • Headers

3.1. HTTP Methods

Tab. 3.6. 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.

3.2. HTTP Statuses

Tab. 3.7. HTTP Status Families
Code Description
1XX Informational
2XX Successful
3XX Redirection
4XX Client Error
5XX Server Error

3.2.1. 1xx Informational response

Tab. 3.8. HTTP Statuses 1xx Informational response
Code Status Description
100 Continue  
101 Switching Protocols  
102 Processing (WebDAV)  
103 Early Hints  

3.2.2. 2xx Success

Tab. 3.9. 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  

3.2.3. 3xx Redirection

Tab. 3.10. 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  

3.2.4. 4xx Client errors

Tab. 3.11. 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  

3.2.5. 5xx Server errors

Tab. 3.12. 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  

3.3. HTTP Headers

3.3.1. HTTP Request Headers

Tab. 3.13. 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  

3.3.2. HTTP Response Headers

Tab. 3.14. 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  

3.4. MIME types

3.4.1. General structure

type/subtype
Tab. 3.15. 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

3.4.2. Text Types

Tab. 3.16. Text Types
MIME type Description
text/plain  
text/html  
text/css  

3.4.3. Application Types

Tab. 3.17. 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/*  

3.4.4. Multipart Types

Tab. 3.18. Multipart Types
MIME type Description
multipart/form-data  
multipart/byteranges  

3.4.5. Image Types

Tab. 3.19. 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  

3.4.6. Audio Types

Tab. 3.20. 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/*  

3.4.7. Video Types

Tab. 3.21. 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

3.5. API Versioning

3.5.1. Good Engineering Practices

  • Always version API
  • Have stable API!
  • Do not use plural in resources
  • Use HTTP Statuses
  • Use HTTP Methods

3.5.2. How to version API?

  • Semantic versioning
  • Django versioning
  • API deprication policy
Tab. 3.22. 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