@PeterHilton http://hilton.org.uk/ HTTP APIs demystified Peeling back the top layer of the web application stack 

Internet technology is like an onion: there’s always another layer. @PeterHilton • 2 

A long time ago… 

A long time ago… 1945 First description of a link-based information system. 1965 The term ‘hypertext’ coined for text containing links. 1970s Many hypertext computer systems implemented. 1980s The Internet becomes widely used by scientists. 1989 WorldWideWeb project introduces HTML to describe hypertext documents, and HTTP to fetch them via Internet. 1991 HTTP 0.9, 1996 HTTP 1.0, 1997-1999 HTTP 1.1 2015 HTTP 2 4 @PeterHilton • 

HTTP = hypertext + Internet 5 @PeterHilton • The Internet is a communications network. HTTP - Hypertext Transfer Protocol is an Internet communication protocol. HTML - Hypertext Markeup Language is a text-based markup language for writing hypertext documents. Internet + HTTP + HTML = the web 

HTTP in action 

No content

Greeting

Hello, world!

hello.html 

https://hilton.org.uk/hello.html URL Uniform Resource Locator (address) 

https://hilton.org.uk/hello.html https scheme (transfer protocol) /hello.html (resource) URL path host (server) name http://hilton.org.uk 

https://hilton.org.uk:3000/hello 80 is the default port in a URL port number 

$ telnet www.x.com 80 Trying 160.153.63.10... Connected to x.com. Escape character is '^]'. GET / HTTP/1.1 Host: www.x.com HTTP/1.1 200 OK Date: Wed, 20 Jan 2021 09:13:04 GMT Server: Apache Upgrade: h2,h2c Connection: Upgrade Last-Modified: Fri, 14 Jul 2017 16:28:12 GMT ETag: "5a200a1-1-55449890c4e78" Accept-Ranges: bytes Content-Length: 1 Vary: User-Agent Content-Type: text/html x 

Internet HTTP request HTTP response client server 

$ telnet www.x.com 80 Trying 160.153.63.10... Connected to x.com. Escape character is '^]'. GET / HTTP/1.1 Host: www.x.com HTTP/1.1 200 OK Date: Wed, 20 Jan 2021 09:13:04 GMT Server: Apache Upgrade: h2,h2c Connection: Upgrade Last-Modified: Fri, 14 Jul 2017 16:28:12 GMT ETag: "5a200a1-1-55449890c4e78" Accept-Ranges: bytes Content-Length: 1 Vary: User-Agent Content-Type: text/html x } }response request 

HTTP request in detail 

GET /hello.html HTTP/1.1 Host: localhost:3000 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.93 Safari/537.36 Accept: text/html,application/xhtml+xml,application/ xml;q=0.9,image/webp,*/*;q=0.8 Accept-Encoding: gzip, deflate, sdch Accept-Language: en-GB,en;q=0.8,nl;q=0.6,fr;q=0.4 Cache-Control: max-age=0 Connection: keep-alive Upgrade-Insecure-Requests: 1 

Form Send 

POST /form HTTP/1.1 Host: localhost:3000 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/601.6.17 (KHTML, like Gecko) Version/9.1.1 Safari/ 601.6.17 Content-Length: 24 Accept: text/html,application/xhtml+xml,application/ xml;q=0.9,*/*;q=0.8 Accept-Encoding: gzip, deflate Accept-Language: en-us Connection: keep-alive Content-Type: application/x-www-form-urlencoded Dnt: 1 Origin: file:// colour=blue&fruit=banana 

HTTP request methods GET - fetch a resource HEAD - returns the same headers as GET, but no body POST - send a resource PUT - replace a resource DELETE - delete a resource TRACE, OPTIONS, LINK, UNLINK, PATCH 19 @PeterHilton • 

HTTP response in detail 

HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 16 Jul 2016 11:47:50 GMT Content-Type: text/html; charset=utf-8 Content-Length: 147 Last-Modified: Sat, 16 Jul 2016 08:27:20 GMT Access-Control-Allow-Origin: * Expires: Sat, 16 Jul 2016 11:57:50 GMT Cache-Control: max-age=600 Accept-Ranges: bytes X-GitHub-Request-Id: 53A0612B:15F4:2FDF3B:578A1EE6 Greeting

Hello, world!



HTTP/1.1 200 OK response status code status text 

HTTP APIs 

The other kind of application interface An application user interface (UI) lets you interact with an application by human (user) interaction. An application programming interface (API) lets you interact with an application by programming software to do so. 24 @PeterHilton • 

‘Loading a web page’ HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 16 Jul 2016 11:47:50 GMT Content-Type: text/html; charset=utf-8 Content-Length: 147 Cache-Control: max-age=600 Last-Modified: 16 Jul 2016 08:27:20 GMT Expires: Sat, 16 Jul 2016 11:57:50 GMT Access-Control-Allow-Origin: * Accept-Ranges: bytes Greeting

Hello, world!

‘Calling an API’ HTTP/1.1 200 OK Server: GitHub.com Date: Wed, 20 Jan 2021 09:38:36 GMT Content-Type: application/json; charset=utf-8 Content-Length: 78 Cache-Control: max-age=600 Last-Modified: Wed, 20 Jan 2021 09:38:36 GMT Expires: 20 Jan 2021 09:48:35 Access-Control-Allow-Origin: * Accept-Ranges: bytes { "message": { "content": "Hello, world!", "type": "Greeting" } } 

‘Submitting a form on a web page’ POST /form HTTP/1.1 Content-Length: 24 Content-Type: application/ x-www-form-urlencoded colour=blue&fruit=banana ‘Calling an API’ POST /api HTTP/1.1 Content-Length: 78 Content-Type: application/json { "message": { "content": "Hello, world!", "type": "Greeting" } } 

The tricky details 

HTTP response status codes 28 @PeterHilton • 100-199 Informational 200-299 Client request successful 300-399 Request redirected, further action necessary 400-499 Client error - do not repeat the same request 500-599 Server error - maybe try again About 60 defined status codes, in the above five groups https://en.wikipedia.org/wiki/List_of_HTTP_status_codes 

HTTP header fields (‘HTTP headers’) 29 @PeterHilton • General headers are used in both request and response Request headers indicate client preferences and config Response headers provide information about the server Entity headers describe the request or response body Non-standard headers are application-specific About 50 defined standard headers https://en.wikipedia.org/wiki/List_of_HTTP_header_fields 

Things that everyone gets wrong Character encodings URL encoding/decoding Caches and proxies Cookies, and using them to introduce ‘session’ state Documenting an API 30 @PeterHilton • 

Further reading 31 @PeterHilton • Web Client Programming with Perl (O’Reilly, 1997), free online via O’Reilly Open Books, starts with three well- written chapters that teach everything web developers need to know about HTTP: Chapter 1: Introduction Chapter 2: Demystifying the Browser Chapter 3: Learning HTTP http://www.oreilly.com/openbook/webclient/ 

HTTP: The Definitive Guide 658 pages. 1035 grams. I have not read this book. Few developers need this much detail. 32 @PeterHilton • 

@PeterHilton http://hilton.org.uk/