RESTful Web Services A MIDAS MISSION PRESENTATION APRIL 29, 2015

About the presenter  John Levander  a Software Development Manager for the Informatics Service Group (ISG)  – DBMI, University of Pittsburgh  Working heavily in the Web services realm for about 7 years

About the talk  Talk is targeted at developers but not so much that non-developers will be lost.  Feel free to interrupt if you have a question. We have plenty of time.  I reserve the right to ask fellow ISG team members to help field any questions, so ISG people stay on your toes.

My MISSION for this talk  To explain what RESTful Web Services are, and why they are useful.  To explain at a basic level, how RESTful Web Services work.  If I succeed, you will be prepared for the next talk and the following exercise

What are Web services?  Software that is exposed to the internet (via HTTP) for programmatic access  May help to think of Web services as remote libraries that you can call from your code  Familiar with importing local libraries (on your machine) into your code:  C – #include  Java – import java.lang.Math  Python – import math  Web services allow you to use remote libraries that run on another machine

Self-contained application This works well if: 1. All libraries can run in a single environment, for example: 1. Math libraries 2. Charting libraries 3. Compression libraries Application Executable Library 1 Your code Library 2 Library 3

Web service enabled application Application Executable Weather Forecast Your code Current Traffic Top News Stories

Web services are not Web applications  Web applications are for human consumption  Web services are for computer consumption  NIH is adopting the term Web based API Interface for a Web application Interface for a Web service

Benefits of Software hosted as a Web Service  Interoperability  Safe way to make your software available  Code re-use

Benefit: Interoperability  Programming language, platform, and vendor independent  Generic data exchange format Web Service Windows PC C++ Application Android Java Application Apple Swift Application HTTP

Benefit: Safe way to make your your software available  You keep your code secure, behind your firewall  Nobody is going to steal your product through a web service  Self-contained applications are susceptible to reverse engineering  You control who has access to run your code (authorization) Client Web Service Protected Code

Benefit: Code re-use  Multiple applications can use the same web service Web Service (Login with Facebook!) Weather Application Messaging Application Gaming Application

Summary  Defined a Web service  Web service vs. Web application  The benefits of hosting your application as a Web service

Structure of this talk  What are RESTful Web Services  HTTP Message Exchange  How Web Browsers exchange data with Web Servers  How Programmatic WS-Clients exchange data with RESTful Web Services  RESTful Web Services  The REST style  Exercise: Create an API for a RESTful Web Service  JSON

What are RESTful Web Services?  RESTful Web services:  A style of Web service that works very well with “plain” HTTP (lightweight)  Very popular style of Web service (all the cool kids have one).  Other types of Web services (add protocols on HTTP – heavyweight)  HTTP – HyperText Transfer Protocol  Defines how clients (like web browsers) make requests and how Web servers respond when communicating over the Web.

Structure of this talk  What are RESTful Web Services  HTTP Message Exchange  How Web Browsers exchange data with Web Servers  How Programmatic WS-Clients exchange data with RESTful Web Services  RESTful Web Services  The REST style  Exercise: Create an API for a RESTful Web Service  JSON

HTTP Message Exchange

Web Browser HTTP Message Exchange  Web Browser :  Client (browser) sends an HTTP Request to Web server  Web Server usually responds with HTML (meant for human consumption) Web Server HTTP Request HTML

HTTP Message Exchange WS Client  Web Service :  Client sends an HTTP Request to Web service  Web Service responds with some form of computer parse-able structured data Web Service HTTP Request Structured data (no presentation information)

HTTP Request Messages (Call from Web browser) Example Web Browser HTTP Request to Web Server: GET /weather/today/15223 HTTP/1.1 Host: Accept: text/html Web Browser Web Server HTTP Request

HTTP Response Messages (Response to Web browser) HTTP/ OK Content-Type: text/html Weather forecast… … Web Browser Web Server HTTP Response (HTML) Example HTTP Response from Web Server to Web Browser :

HTTP Request Messages (Call from Programmatic WS-Client) GET /api/weather/temp/zip/15223 HTTP/1.1 Host: Accept: application/json Web Service HTTP Request WS Client Example WS-Client HTTP Request to a RESTful Web Service :

HTTP Response Message (Response from Web server) Web Service HTTP Response (JSON) WS Client Example HTTP Response from Web service to a WS-Client HTTP/ OK Content-Type: application/json { temp: 67 }

The Response Status Line Status-CodeReason-Phrase 200OK 403Forbidden 404Not Found 500Internal Server Error HTTP/ OK Content-Type: text/html { temp: 67 }

Structure of this talk  What are RESTful Web Services  HTTP Message Exchange  How Web Browsers exchange data with Web Servers  How Programmatic WS-Clients exchange data with RESTful Web Services  RESTful Web Services  The REST style  Exercise: Create an API for a RESTful Web Service  JSON

RESTful Web Services

REST, what is it?  REST – REpresentational State Transfer  Describes an style of of how networked programs communicate  REST IS NOT A PROTOCOL, it’s just a style.  REST style + Web Service = RESTful Web Service  …So what does a RESTful Web Service look like?

Exercise: Design a RESTful Web Service API  Design a small Web Service in the REST style (i.e. a RESTful Web Service)

Requirements for an Example RESTful Web Service API For the exercise, we will define a simple Web service to store information about movies. (Think about it as the smallest version of IMDB possible.) Actions:  Allow a user to view data about a movie  Movie title  Year produced  Synopsis  Allow a user to search for a movie by title

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

Step 1: Identifying the key datatypes (resources)  The datatypes that you want to make accessible on a RESTful Web Service are known as resources  Library -> Book, magazine, videos  We refer to these these resources using a Universal Resource Identifier (URI)  These resources are nouns, and do not include verbs  E.g. Naming a resource“getBook” would not be RESTful

Step 1: Identifying the key datatypes (resources) cont’d…  What resources should we expose on our system?  Movie  Collection of movies (for search!)  At this point we have successfully identified our resources…

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

… now we have to choose how the resources will be addressed on our Web Service. We address resources using URIs. We define the following URIs  For a movie - /api/movie/{movie_id}  reference a movie in the system using an id number  For the collection of all movies - /api/movies  references the entire collection of movies on our system  It’s good practice to reference instances of resources by ID number in a RESTful system, as “names” of resources may change Step 2: Assigning the URIs

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

Step 3: Defining our Service Methods  RESTful Web Services use HTTP to communicate.  HTTP defines methods (verbs). GET /api/weather/temp/zip/15223 HTTP/1.1 Host:

HTTP Methods  HTTP Requests specify an HTTP METHOD  GET – retrieve whatever information is defined by the Request-URI  POST – store the enclosed data with the data already at the supplied Request-URI  PUT – store the enclosed data at the supplied Request- URI  DELETE – delete the resource identified by the Request- URI

Step 3: Defining the service methods  RESTful Web Services use HTTP to communicate.  HTTP defines methods (verbs).  The combination of an HTTP method (e.g. GET) and a URI (e.g. /api/movies) defines a method.  Think of this as a method named getMovies() in a normal system…this is why we can’t use verbs in resource definitions! GET /api/weather/temp/zip/15223 HTTP/1.1 Host:

Step 3: Defining the service methods Collection Methods:  GET /api/movies/  Action: show all movies in the system  GET /api/movies/?title=  Action: search all movies in the system by title  POST /api/movies/  add a movie

Step 3: Defining the service methods Resource Methods:  GET /api/movie/{movie_id}  Retrieve the information stored about a movie in the system, given id  DELETE /api/movie/{movie_id}  Delete a movie from the system, given id

Step 3 Complete!  We’ve finished defining our service methods, now we need to define what arguments/parameters these methods take…

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

Step 4: Defining the method parameters  REST Web Services can accept many types of data as parameters.  Obviously, they can accept parameters in the URI  /api/movie/ {movie_id}  But what if we want our method to accept a complex data structure as a parameter?  We send the structure in the BODY of the HTTP request using a process called Content Negotiation

Step 4: Defining the method parameters  It turns out all of our methods accept parameters in the URI, except for  POST /api/movies …which adds a movie to the system.  For this exercise, our POST /api/movies method will accept a representation of a movie, in JSON format.  To specify this in the interface however, we will simply say that the  Method: POST /api/movies, Accepts: application/json

Content Negotiation Example: Add a movie to our system HTTP Request: POST /api/movies HTTP/1.1 Content-type: “application/json” { “title”: “Top Gun”, “year”: 1986, “synopsis”: “A fighter pilot…” }

Content Negotiation Example: Response after a movie is added HTTP Response: HTTP/ OK

Step 4 Complete!  GET /api/movies  GET /api/movies?title=  POST /api/movies  Accepts: “application/json”  GET /api/movie/{movie_id}  DELETE /api/movie/{movie_id} We’ve defined all of our method parameters, our API so far…

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

Step 5: Define the method return types  Content negotiation also works for return types.  The method can specify what type of content it will return from a method call.  In the interest of time, in this exercise:  all of our GET methods will return JSON in the response body  Our other methods will not have a response body

Exercise: Designing the API 1. Identify key datatypes (resources) 2. Assign URIs for these datatypes 3. Define the service methods (method “names”) 4. Define the service method parameters 5. Define the service method return types

Final API Definition  GET /api/movies  Returns: “application/json”  GET /api/movies?title=  Returns: “application/json”  POST /api/movies  Accepts: “application/json”  GET /api/movie/{movie_id}  Returns: “application/json”  DELETE /api/movie/{movie_id} Share your RESTful API definition however you like!

Example Use of the API GET /api/movies w/search!  requests.get( ' headers={'Accept':'application/json’})  Returns:

Example Use of the API GET /api/movie  requests.get( ' headers={'Accept':'application/json’})  Returns:

RESTful Web Service Section Summary  REST is a style, not a protocol  How RESTful APIs are defined  Run over “basic” HTTP  URI / resources  HTTP Methods  Content Negotiation  How RESTful APIs are shared (no machine interpretable service definition)  Basic example usage of a RESTful interface

Structure of this talk  What are RESTful Web Services  HTTP Message Exchange  How Web Browsers exchange data with Web Servers  How Programmatic WS-Clients exchange data with RESTful Web Services  RESTful Web Services  The REST style  Exercise: Create an API for a RESTful Web Service  JSON

JSON AND A BREIF WORD ABOUT OTHER MESSAGE EXCHANGE FORMATS

What can we put in the message body of an HTTP message?  REST doesn’t define a data exchange format, you are free to use whatever fits your needs.  Format should be language independent.  One popular choice:  JSON (we’ve seen a lot of JSON a ready)

Data Exchange Format- JSON (JavaScript Object Notation)  JSON is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. – json.org  Based on a subset of the JavaScript Programming Language  Based on:  Name-value pairs  Ordered lists of values (aka arrays, vectors, lists, sequences)

Example JSON Document

A word on other data exchange formats…  XML  CSV

Structure of this talk  What are RESTful Web Services  HTTP Message Exchange  How Web Browsers exchange data with Web Servers  How Programmatic WS-Clients exchange data with RESTful Web Services  RESTful Web Services  The REST style  Exercise: Create an API for a RESTful Web Service  JSON

Questions?  Contact info:  John Levander