restful web services a midas mission presentation april 29, 2015

RESTfulWeb ServicesA MIDAS MISSION PRESENTATIONAPRIL 29, 2015

About the presenter

John Levander ([email protected]) 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

mailto:[email protected]

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.






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://www.weather-example.com/

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 }






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…

… 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

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…

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…

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

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






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






JSON

Questions?

Contact info: John Levander ([email protected])

mailto:[email protected]

restful web services a midas mission presentation april 29, 2015

Documents