Transport & APIs

How do we talk to servers?

  • 7-Layer OSI Model
  • We make requests
  • which are addressed to a domain (e.g. www.google.com)
  • which is mapped to an external IP (e.g. 8.8.8.8)
  • the request goes to our ISP and then...
  • out through a sea of routers (all with routing tables)
  • until a server attached to that router is confirmed
  • the server responds and the route is re-traced back to the client and on to the target server.
     

How is this possible??

 

Protocols

  • HTTP(S) - HyperText Transfer Protocol (Secure)

  • FTP - File Transfer Protocol

  • SMTP - Simple Mail Transfer Protocol (href="mailto: ...")

    • POP3 - Post Office Protocol

  • GIT

  • WS - Web Sockets

  • SSH - Secure Shell

  • TEL - Telephone Service (href="tel: ...")

  • SMS - Short Messaging Service (href="sms: ...")

  • skype, telnet, IRC, etc. etc.

Defn: A set of conventions governing the treatment and especially the formatting of data in an electronic communications system

HTTP(S)

What can we send/receive?

  • Static Code Files
    • inc. files templated by the server
    • files like .js, .css,
    • .doc, .pdf
  • Data
    • xml
    • JSON <-- this is the preferred way we send data

 

List of common types

Sending Data (JSON)

  • JavaScript Object Notation
  • Turns js arrays and objects into transportable string
  • Natural methods for conversion:  
    • JSON.stringify(obj/arr) - prepare for transport
    • JSON.parse(str) - decode post-transport
    • demo
[
  {
    name: 'James',
    age: 40,
    isDeveloper: true  
  }
]
[
  {
    "name": "James",
    "age": 40,
    "isDeveloper": true  
  }
]

stringify

parse

Notes on stringify

Ways to use https

Endpoints (What we want)

  • You send your request to a URL where you believe (or have been told) the resource you're looking for is located
  • You aim it at a domain (e.g. https://newsapi.org)
  • You give it a path (e.g. /v2/everything)
    • generally indicating the resource you want or the function (CRUD) that you're trying to trigger
  • You may include further information
    • in the url query string (e.g. ?q=bitcoin)
    • or the request body
    • generally used to pass further info on the response required (e.g. 'what you're looking for', 'how many results per "page", etc.)

Methods (aka HTTP VERBS) (What we want to do with it)

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS

Full List: https://www.iana.org/assignments/http-methods/http-methods.xhtml

GET

  • GET is when you just ask for a resource
  • Your browser makes GET requests when you enter a URL in the address bar and hit return
  • GET is the default method on an HTML Form
  • GET requests have no body, so any information you need to pass with the request to enable the server to make choices is put in the parameters: /users?p=1
  • If you're sending private information don't use GET

POST

  • POST is when you want to send information to a server privately
  • POST requests have a request body in which the information is stored (basically it's like an object)
  • POST often sends NEW information to a server

PUT

  • PUT works like POST except that it is meant to send information to update information the server currently holds
  • It's supposed to be for upsert-ing (add or replace in collection)
  • PUT also has a request body
  • body usually contains the changes to a record

DELETE

  • DELETE does what it says on the tin
  • It does have a request body but it didn't used to and its use is sketchy at best...

HEAD, PATCH & OPTIONS

  • HEAD gets the headers you'd get if you made a GET request to that URL
    • Headers are a list of key-pair values you can send with a request to help the two machines understand how to deal with the request.
  • PATCH is meant to be for partial updating of a resource
  • OPTIONS shows what methods are available (so it might return [GET, POST, OPTIONS]

HTTP HEADERS

See here for standard headers

Headers are information the transportation layer needs to know about, not your application. (Think 'baggage tags')

 

Headers contain 'meta' information about the call itself:

  • How is it encoded?
  • What response type will it accept in return?
  • Does it have a security token?

 

Headers can be the standard ones or you can make your own custom ones.

demo

How do we know if it is successful or not?

HTTP Status Codes

  • 100s - information [for an ongoing process]
    • 100 CONTINUE (for things like websockets)
  • 200s - success (Here you go!)
    • 200 OK
    • 201 CREATED
  • 300s - redirection (location has/may change[d])
    • 302 FOUND
  • 400s - client errors (You f*cked up)
    • 400 - BAD REQUEST
    • 401 - UNAUTHORISED
    • 404 - NOT FOUND
  • 500s - server errors (I f*cked up)
    • 500 - SERVER ERROR

Full List:

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

 

As cats: https://http.cat/

As dogs: https://httpstatusdogs.com/

What can we contact?

Services

APIs

  • Stands for: Application Programming Interface
  • Allow users to interact with and use your business services
  • APIs are for intelligent interaction
  • Many Types
  • You CAN modify records that it holds
  • You CAN send commands that will enact events (possibly real life ones)
  • Examples: Booking a delivery slot with tesco or manipulating tweets from a twitter account
  • We will look at REST APIs

What is REST?

  • REpresentational State Transfer
  • Sharing the state of your app between the client and server to keep them in sync
  • e.g. Shopping basket:
    • See what's in basket
    • Add to basket
    • Modify basket items (quantity, colour options, etc.)
    • Remove from Basket
  • CRUD (Create, Read, Update & Delete)
  • Synonymous with POST, GET, PUT, DELETE
  • The system runs off intelligently structured URLs:
    • GET /cars <-- Gets all the cars
    • GET /cars/23j4hkh23k3 <-- Gets one car
    • POST /cars <-- Adds a car to the list
  • Demo (for memory purposes only!)

Example API Docs

https://stripe.com/docs/api/charges

THE POSTMAN CLIENT

Mock REST API

 

Other famous fake APIs

 

Example of making a fake API (whilst you're waiting for server-side devs to complete??):

https://github.com/jmsherry/fake-server