REST and Web Services

What is a web service?

• Up to now we’ve said that a web server delivers html to clients
• Consider this web page: Olin College Engineering Courses
• What would “TeachBack” do if it wanted to have a list of courses pre-populated with a college’s courses?
  • Grab all the text curl http://wikis.olin.edu/coursecatalog/doku.php?id=course_listings:engr > olincourses.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

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
• Discussion: What are some of the big differences between calling a gem’s API and calling a web service API?. Performance? Error handling and recovery? Security? Cost sharing?

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 SystemsRetrieving information

One level deeper

RPC - Remote Procedure Calls

• Imagine a procedure (method) : return_fortune_cookie.
• 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.facebok.com/users
  • GET 0.0.0.0:3000/cards/1.xml
• Some things are harder to fit with the model
  • What might a fortune cookie service look like as REST?
  • The ‘resource’ here is a single fortune
  • http://cookieserver.org/fortunes/1
  • http://cookieserver.org/fortunes
  • http://cookieserver.org/fortunes/random
• Note fortunes/random, random is not exactly identifying a resource; but close enough.
• What if caching was done strictly by url?
  • Two 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

Leveraging Web Services

• There are many many different kinds of services that deliver their info over a web service.
• Use google and Programmable Web has thousands of APIs you can use
  • You might have to call a service directly (using HTTP)
  • You might find a gem to provide a nicer, limited, ruby apii to the service
  • You might elect to build your own gem
• Good design practice to isolate details of the web service from the rest of the code

Security, Authentication, Money

• Several reasons why a service might need authentication
  • They want to charge for it
  • They want to force you to register with them so they know who you are
  • They simply want to put in a speedbump
• Most typicall technique
  • You register on their site (manually) and they give you api token of some kind (a random string)
  • Every call to the service includes a mandatory paramter

Case study

• (Borrowed from Trade Assistant)
• Problem: Need to get an assortment of information about stocks: price quotes, historical info, and so on.
• Steps to solve the problem
  1. Locate an appropriate web service, with google and progammable web site
  2. Investigate whether there is an API, is it REST, is it free or does it cost, do they have the data I want
  3. A bunch of googling led me to two candidates: Yahoo Stocks Api and Markit On Demand
  4. Experiment to see if they do what I need. See Github Webservicedemo
  5. Build a class or set of classes to encapsulate the API calls. Consider isolation from web service , error handling, caching of common results.
• Key Gems to make your life good: typhoeusXmlSimple

Delivering Web Services

• Providing a Web API from your server
• Often nice to provide sample code and a ‘binding’ to a language
• Need to decide on the url (REST!)
• Latest thinking is that you should not base it on your underlying relational database structure.
• In other words, to get title of course 3’s lecture 4
  • Don’t specify: http://teachback/api/course/3/lecture/4/title
  • Do specify: http://teachback/api/course_info?code=COSI-234 -> xml structure with info about that course.

Case Study

• Goal: Your server needs to respond to HTTP GET for this url: http://teachback/api/course_info?code=COSI-234
  • Controller: api
  • Action: course_info
  • Parameter: code=COSI-234
• Let’s take a look at the code in Webservice Demo
• Try this url: http://0.0.0.0:3000/api/course_info.xml?course=aaa