Post on 06-Jan-2018
description
RESTfulWeb ServicesA MIDAS MISSION PRESENTATIONAPRIL 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
This works well if:1. All libraries can run
in a single environment, for example:1. Math libraries2. Charting libraries3. Compression
librariesApplicationExecutable
Library 1
Yourcode
Library 2Library 3
Web service enabled application
ApplicationExecutable
Weather Forecast
Yourcode
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 APIInterface 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
WebService
Windows PCC++
Application
AndroidJava
Application AppleSwift
Application
HTTP
HTTP
HTTP
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 WebService
ProtectedCode
Benefit: Code re-use
Multiple applications can use the same web service
WebService
(Login with Facebook!)
WeatherApplication
MessagingApplication
GamingApplication
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 MessageExchange
WebBrowser
HTTP Message Exchange
Web Browser: Client (browser) sends an HTTP Request to Web
server Web Server usually responds with HTML (meant for
human consumption)
WebServe
r
HTTP Request
HTML
HTTP Message Exchange
WSClient
Web Service: Client sends an HTTP Request to Web service Web Service responds with some form of computer
parse-able structured data
WebServic
e
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.1Host: www.weather-example.comAccept: text/html
WebBrowser
WebServe
r
HTTP Request
HTTP Response Messages(Response to Web browser)
HTTP/1.1 200 OKContent-Type: text/html
<!DOCTYPE html><html><title>Weather forecast…</title>…</html>
WebBrowser
WebServe
rHTTP 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.1Host: www.weather-example.comAccept: application/json
WebServic
e
HTTP RequestWSClient
Example WS-Client HTTP Request to a RESTful Web Service:
HTTP Response Message(Response from Web server)
WebServic
eHTTP Response (JSON) WS
Client
Example HTTP Response from Web service to a WS-Client
HTTP/1.1 200 OKContent-Type: application/json
{ temp: 67 }
The Response Status Line
Status-Code Reason-Phrase200 OK403 Forbidden404 Not Found500 Internal Server Error
HTTP/1.1 200 OKContent-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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. 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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. 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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. 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.1Host: 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
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.1Host: www.weather-example.com
Step 3:Defining the service methods
Collection Methods: GET /api/movies/
Action: show all movies in the system GET /api/movies/?title=<search term>
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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. 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 systemHTTP Request:
POST /api/movies HTTP/1.1Content-type: “application/json”
{
“title”: “Top Gun”,
“year”: 1986,
“synopsis”: “A fighter pilot…”
}
Content Negotiation Example:Response after a movie is addedHTTP Response:
HTTP/1.1 200 OK
Step 4 Complete!
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}
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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. 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 datatypes3. Define the service methods (method “names”)4. Define the service method parameters5. Define the service method return types
Final API Definition
GET /api/movies Returns: “application/json”
GET /api/movies?title=<search term> 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 APIGET /api/movies w/search! requests.get(
'http://www.example.com/api/movies?title=age', headers={'Accept':'application/json’})
Returns:
Example Use of the APIGET /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
JSONAND 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