HTTP APIs demystified

@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

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Greeting</title> </head> <body>
<h1>Hello, world!</h1> </body> </html> 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

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Form</title> </head> <body>
<form method="post" action="http://localhost:3000/form"> <input name="colour" value="blue"> <input name="fruit" value="banana"> <button>Send</button> </form> </body> </html>

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 <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Greeting</title> </head> <body> <h1>Hello, world!</h1> </body> </html>

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 <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Greeting</title> </head> <body> <h1>Hello, world!</h1> </body> </html> ‘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/

HTTP APIs demystified

HTTP APIs demystified

Peter Hilton

More Decks by Peter Hilton

Other Decks in Technology

Featured

Transcript

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

Internet technology is like an onion: there’s always another layer.

A long time ago…

A long time ago… 1945 First description of a link-based

HTTP = hypertext + Internet 5 @PeterHilton • The Internet

HTTP in action

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Greeting</title> </head> <body>

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

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

$ telnet www.x.com 80 Trying 160.153.63.10... Connected to x.com. Escape

Internet HTTP request HTTP response client server

$ telnet www.x.com 80 Trying 160.153.63.10... Connected to x.com. Escape

HTTP request in detail

GET /hello.html HTTP/1.1 Host: localhost:3000 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Form</title> </head> <body>

POST /form HTTP/1.1 Host: localhost:3000 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac

HTTP request methods GET - fetch a resource HEAD -

HTTP response in detail

HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 16 Jul 2016

HTTP/1.1 200 OK response status code status text

HTTP APIs

The other kind of application interface An application user interface

‘Loading a web page’ HTTP/1.1 200 OK Server: GitHub.com Date:

‘Submitting a form on a web page’ POST /form HTTP/1.1

The tricky details

HTTP response status codes 28 @PeterHilton • 100-199 Informational 200-299

HTTP header fields (‘HTTP headers’) 29 @PeterHilton • General headers

Things that everyone gets wrong Character encodings URL encoding/decoding Caches

Further reading 31 @PeterHilton • Web Client Programming with Perl

HTTP: The Definitive Guide 658 pages. 1035 grams. I have

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