REST and Web Services

SOA and REST and Services

• Consider this web page: Brandeis Course Catalog
• What would schdl.net do if it wanted to have a list of courses pre-populated with a college’s courses?
  • Grab all the text curl http://registrar-prod.unet.brandeis.edu/registrar/schedule/classes/2019/Spring/1400/all > brandeiscourses.txt
  • Write a program to parse that page and then load the results into a database.
  • This is called “scraping” and usually that would violate a copyright
• Server can also deliver information in “machine readable” formats (such as JSON or XML)
• The term “API” is used to describe the permissable ways that one program can call another, such as a library
• Web Service API is when this is between servers on the internet
• The Brandeis Course Catalog implements such an API! Readme for Registrar’s Web Service. Actual JSON Data

Protocols

• This can be done with many different standards and formats and protocols
  • SOAP: Simple Object Access Protocol
  • XMLRPC: XML-RPC
  • REST: Representational State Transfer – our focus

Pause to look at the big picture

• Servers on the internet, anywhere, can be called as objects and methods
• Resources of all kinds can be offered to clients with no coordination
• The internet becomes a huge, amazing Operating System

One level deeper

RPC - Remote Procedure Calls

• Imagine a procedure (method): get_horoscope(date, sign) => String
• So for example: get_horoscope("march 22, 2015", "aries") which returns a sentence of text (not html!)
  • I could use it to improve my calendar app to optionally display the user’s horoscope
  • Or, I could use it to create a twitter “robot” to answer a tweet with my horosc
• What would it mean to call it between two computers?
• What would it mean to call it between two computers over the internet?
• How would you approach it?
• REST - A different way to think about RPC

REST based on HTTP: Mini review

• HTTP Verbs: GET (HEAD), PUT, POST, DELETE.
• Think of everything in terms of a ‘resource’ that is being manipulated
• For example, GET means get a representation of the resource marked, e.g.
  • GET http://www.facebook.com/user/pitosalas
  • GET http://www.facebook.com/users
  • GET http://myaddressbook.com/cards/1.xml
• Also consider nested or associated resources
  • GET http://www.nanotwitter.com/user/pitosalas/tweets/10231
• Some things are harder to fit with the model
  • What might a fortunecookie service look like as REST?
  • The ‘resource’ here is a single fortune
    • http://myfortunes.org/fortune/1
    • http://myfortunes.org/fortune
  • But things get weird, and don’t necessarily feel like a resource
    • http://myfortunes.org/fortune/random
    • http://myfortunes.org/fortune?about=money
    • http://myfortunes.org/fortune/create

• Note fortunes/random, random is not exactly identifying a resource; but close enough.

• What if caching was done strictly by url? Advantages:
  • some rhyme or reason on how to build urls and
  • make logical use of url space
  • Different ‘representations’ possible: html and xml, but others too, say csv or video
  • Big one: Standards allow caching in the cloud. But what about ‘random’ case? TTL!

Let’s play with it!

• Here’s the web site for Fortunes
• Here’s the code for it Fortunes RAILS Source code

GraphQL

• New kid on the block
• Not clear yet whether it will become a standard
• Addresses the case of “multi-model” APIs
• Instead of having a bunch of “dumb” REST endpoints, have a single “smart” endpoint
• Inputs are simple, JSON ‘query’ structures, and outputs are JSON result structures
• Handled via a “resolver” that you write
• It is its own service and does not have to be tied to your schema, or even whether you have a schema!
• Using GraphQL for nanoTwitter
  • Replace the whole or part of your REST API with a single GraphQL resolver
  • The resulting APIs need to be sufficient to write a simple nanoTwitter client (say on iOS)
  • Why?
    • No Scaling advantage
    • Possibly less work to do (not sure ahead of time)
    • Learn GraphQL
    • Learn a new architectural pattern

Input to Github’s GraphQL endpoint

• Play here: https://developer.github.com/v4/explorer/

 query {
   user(login: "pitosalas") {
     repositories(first:10 ) {
       edges {
         node {
           name
         }
       }
     }
  }
}

Output from Github GraphQL endpoint

 {
   "data": {
     "user": {
       "repositories": {
         "edges": [
           {
             "node": {
               "name": "blogbridge"
             }
          },
          {
            "node": {
              "name": "blogbridge-utils"
            }
          },
          {
            "node": {
              "name": "govsdk"
            }
          },
          {
            "node": {
              "name": "opmlassist"
            }
          },
          {
            "node": {
              "name": "gopml"
            }
          },
          {
            "node": {
              "name": "Tabulator-v1"
            }
          },
          {
            "node": {
              "name": "brandeis-cosci"
            }
          },
          {
            "node": {
              "name": "ilab"
            }
          },
          {
            "node": {
              "name": "DCdigitalVBM"
            }
          },
          {
            "node": {
              "name": "tictactoe"
            }
          }
        ]
      }
    }
  }
}