RESTful
Web Services
A MIDAS MISSION PRESENTATION
APRIL 29, 2015
About the presenter

John Levander (jdl50@pitt.edu)

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 <math.h>

Java – import java.lang.Math

Python – import math
Web services allow you to use remote libraries that
run on another machine
Self-contained application
Your
code
Application
Executable
This works well if:
Library 1
1. All libraries can run in
Librarya 2single environment,
Libraryfor
3 example:
1.
Math libraries
2.
Charting libraries
3.
Compression libraries
Web service enabled application
Weather Forecast
Your
code
Application
Executable
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
Windows PC
C++
Application
Android
Java
Application
HTTP
Apple
Swift
Application
Web
Service
Benefit: Safe way to make your
your software available
Client


Web
Service
Protected
Code
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)
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
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
Browser
HTTP Request
HTML
Web
Server
HTTP Message Exchange

Web Service:

Client sends an HTTP Request to Web service

Web Service responds with some form of computer
parse-able structured data
WS
Client
HTTP Request
Structured data
(no presentation information)
Web
Service
HTTP Request Messages
(Call from Web browser)
Example Web Browser HTTP Request to Web Server:
Web
Browser
HTTP Request
GET /weather/today/15223 HTTP/1.1
Host: www.weather-example.com
Accept: text/html
Web
Server
HTTP Response Messages
(Response to Web browser)
Example HTTP Response from Web Server to Web Browser:
Web
Browser
HTTP Response (HTML)
HTTP/1.1 200 OK
Content-Type: text/html
<!DOCTYPE html>
<html>
<title>Weather forecast…</title>
…
</html>
Web
Server
HTTP Request Messages
(Call from Programmatic WS-Client)
Example WS-Client HTTP Request to a RESTful Web Service:
WS
Client
HTTP Request
Web
Service
GET /api/weather/temp/zip/15223 HTTP/1.1
Host: www.weather-example.com
Accept: application/json
HTTP Response Message
(Response from Web server)
Example HTTP Response from Web service to a WS-Client
WS
Client
HTTP Response (JSON)
HTTP/1.1 200 OK
Content-Type: application/json
{ temp: 67 }
Web
Service
The Response Status Line
HTTP/1.1 200 OK
Content-Type: text/html
{ temp: 67 }
Status-Code
Reason-Phrase
200
OK
403
Forbidden
404
Not Found
500
Internal Server Error
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
Step 2: Assigning the URIs
… 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}


For the collection of all movies - /api/movies


reference a movie in the system using an id number
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
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: www.weather-example.com
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 RequestURI

DELETE – delete the resource identified by the RequestURI
Step 3:
Defining the service methods

RESTful Web Services use HTTP to communicate.

HTTP defines methods (verbs).
GET /api/weather/temp/zip/15223 HTTP/1.1
Host: www.weather-example.com

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!
Step 3:
Defining the service methods
Collection Methods:

GET /api/movies/


GET /api/movies/?title=<search term>


Action: show all movies in the system
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/1.1 200 OK
Step 4 Complete!
We’ve defined all of our method parameters, our API so far…

GET /api/movies

GET /api/movies?title=<search term>

POST /api/movies

Accepts: “application/json”

GET /api/movie/{movie_id}

DELETE /api/movie/{movie_id}
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


GET /api/movies?title=<search term>


Accepts: “application/json”
GET /api/movie/{movie_id}


Returns: “application/json”
POST /api/movies


Returns: “application/json”
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(
'http://www.example.com/api/movies?title=age',
headers={'Accept':'application/json’})

Returns:
Example Use of the API
GET /api/movie

requests.get(
'http://www.example.com/api/movie/26',
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 (jdl50@pitt.edu)