API Design Workshop

API DESIGN

Otavio Ferreira (@otaviofff) August 2010

Agenda 2

The Programmable Web

The Resource-Oriented Architecture

Designing Resource-Oriented Services

Message Parameterization

Standardized Service Clients

Security

Directory of Frameworks

References

HTTP: Documents in Envelopes

Method Information

Scoping Information

The Competing Architectures

The Human Web

Technologies

The Programmable Web 3


4

HTTP

Hypertext Transfer Protocol

Application layer, document-based, request-response

protocol for distributed, collaborative, hypermedia

information systems

Foundation of the Web

Strict envelop structure



5

HTTP Request (1/4)


GET /index.html HTTP/1.1

Host: www.oreilly.com

User-Agent: Mozilla/5.0

Accept: text/xml, text/html, application/xml, ...

Accept-Language: us, en

Accept-Encoding: gzip, deflate

Accept-Charset: ISO-8859, UTF-8

Keep-Alive: 300

Connection: Keep-Alive


6

HTTP Request (2/4)









Keep-Alive: 300


The HTTP method

Indicates how the client

expects the server to

process this envelope.

The path

Indicates the execution

scope.

The HTTP version

Indicates the protocol

version to be considered

by the server while

processing the envelope.


7

HTTP Request (3/4)









Keep-Alive: 300


The request headers

Key-value pairs that act as

informational stickers

slapped onto the envelope.

Parameters that affect the

way the server processes

the request.

There is a standard list of

headers defined in the

protocol specification.


8

HTTP Request (4/4)









Keep-Alive: 300


The entity body

Document inside the

envelope. Object to be

processed by the server.

This particular envelope

has no entity, which means

the envelope is empty.

This is typical for a GET

request, where all the

information needed is in

the path and the headers.


9

HTTP Response (1/4)


HTTP/1.1 200 OK

Date: Mon 26 Jul 2010 15:35:55 GMT

Server: Apache

Last-Modified: Fri 23 Jul 2010 14:01:13 GMT

Accept-Ranges: bytes

Content-Length: 43302

Content-Type: text/html

X-Cache: MISS from www.oreilly.com

Keep-Alive: timeout=15, max=1000


<!DOCTYPE html PUBLIC “...”>

<html>...</html>


10

HTTP Response (2/4)


HTTP/1.1 200 OK

Date: Mon 26 Jul 2010 15:35:55 GMT

Server: Apache









<html>...</html>

The HTTP response code

Numeric code that tells the

client whether the request

succeeded.

Hence, it indicates how the

client should regard this

envelope and its content.

There is a standard list of

response codes defined in

the protocol specification.


11

HTTP Response (3/4)


HTTP/1.1 200 OK

Date: Mon 26 Jul 2010 15:35:55 GMT

Server: Apache









<html>...</html>

The response headers

As with the request

headers, these are key-

value pairs that act as

informational stickers

slapped onto the envelope.

Detail the execution

results, and describe the

entity returned, if any.


12

HTTP Response (4/4)


HTTP/1.1 200 OK

Date: Mon 26 Jul 2010 15:35:55 GMT

Server: Apache









<html>...</html>

The entity body

Again, the document inside

the envelope. This entity is

often referred to as

representation.

It is the fulfillment of the

request message sent by

the client.

The encoding applied to

the entity is presented by

the Content-Type header.


13

Definition

First criterion in classifying Web services

Action to be executed by the server

Values

RESTful services rely on HTTP methods

GET, HEAD, PUT, POST, DELETE

Advantages

Aligned with the overall Web design

Standardized

Method Information


14

Other Approaches

Application-specific method names

Method set in the request path or entity body

Method Information

GET /services/rest/?method=flickr.photos.search&api_key={...}&tags={...} HTTP/1.1

Host: api.flickr.com

GET /services/rest/?method=flickr.photos.delete&api_key={...}&photo_id={...} HTTP/1.1



15

Method Information

POST /search/beta2/ HTTP/1.1

Host: api.google.com

Content-Type: application/soap+xml

SOAPAction: urn:GoogleSearchAction

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<gs:doGoogleSearch xmlns:gs="urn:GoogleSearch">

<q>dog</q>

</gs:doGoogleSearch>

</soap:Body>

</soap:Envelope>


16

Definition

Second criterion in classifying Web services

Execution scope of the HTTP method

Values

RESTful services rely on the request path

Advantages

Aligned with the overall Web design

Applied by Web sites as well

Scoping Information


17

Other Approaches

Application-specific path locations

Scope set in the request entity body

Scoping Information

GET /services/rest/?method=flickr.photos.search&api_key={...}&tags={...} HTTP/1.1


GET /services/rest/?method=flickr.photos.delete&api_key={...}&photo_id={...} HTTP/1.1



18

Scoping Information

POST /search/beta2/ HTTP/1.1

Host: api.google.com

Content-Type: application/soap+xml

SOAPAction: urn:GoogleSearchAction

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<gs:doGoogleSearch xmlns:gs="urn:GoogleSearch">

<q>dog</q>

</gs:doGoogleSearch>

</soap:Body>

</soap:Envelope>


19

Architectural Decisions

The Competing Architectures

Style Method Information Scoping Information

HTTP Verb Entity Body Path (URI) Entity Body Path (URI)

RESTful

RPC

REST-RPC

Embraces the Web

Routes around the Web


20

Scenario

Static Web sites are RESTful

Web applications fall into one of the three

architectural styles, typically REST-RPC

Web browsers are service clients

So the Human Web is on the Programmable Web

Goal

Make the Programmable Web better

More uniform

Better organized

Using the features of HTTP to greatest advantage

The Human Web


21

Classification

Technologies do not classify services

Architectural styles do

Technologies

HTTP

URI

XML-RPC

SOAP

WS-*

WSDL, WADL

XML, JSON, XHTML, RDF, ...

Technologies

Agenda 22






Security


References

Introduction

Concepts

Principles

The Resource-Oriented

Architecture 23


24

Terminology

REST is not an architecture

REST is not tied to the Web

REST is not tied to any set of technologies

REST is a set of design criteria for distributed systems

RESTful services fully adhere to all REST criteria

RESTful services are tied to the Web, HTTP, and URI

ROA is the architecture behind RESTful services

ROA clearly defines its architectural principles

Introduction


25

Concepts

Resource

Representation

Uniform Identifier

Uniform Interface

Principles

Addressability

Connectedness

Statelessness

Introduction


26

Resource

Relevant abstraction within the domain covered

Any domain object, either concrete or abstract

Might be composed of a collection of objects

Resource Examples

Geographical map of Fortaleza, Brazil

Some information about dogs

Directory of resources pertaining to dogs

Version 1.0.3 of the software release

Coldplay’s discography

Alice’s humor

Concepts


27

Identifying Resources

If another party [users] might reasonably want to...

Create a hypertext link to it

Make or refute assertions about it

Retrieve or cache a representation of it

Include all or part of it by reference into another representation

Annotate it

Perform other operations on it

Then, it has to be a resource

Concepts

– Architecture of the World Wide Web, Volume One, 2004, W3C


28

Representation

Any useful information about the state of a resource

Serialization of a resource in any given format

Transferred bidirectionally between client and server

Representation Example (User Object, JSON)

Concepts

{

"nickname" : "otaviofff",

"created" : "2010-07-01T13:15:00-03:00",

"updated" : "2010-08-02T01:31:04-03:00",

"id" : 4332,

"active" : true

}


29

Deciding between Representations

Multiple URIs

HTTP header ”Accept”

HTTP header “Accept-Language”

Other HTTP request metadata

Concepts


30

Uniform Identifier

URI – Uniform Resource Identifier

It is the name and address of a resource

Each resource has to have at least one URI

Uniform Identifier Examples

http://example.com/map/bra/ce/fortaleza

http://example.com/wiki/dog

http://example.com/search/dog

http://example.com/software/release/1.0.3.tar.gz

http://example.com/discography/coldplay

http://example.com/user/alice/humor

Concepts


31

Analyzing Uniform Identifiers

URIs should be descriptive

URIs should have clear, intuitive structure and notation

URIs should vary in predictable ways

Clients may create their own entry points into services

Constraints

Every URI designates one Resource

Every Resource might be designated by various URIs

Defining a canonical URI is a best practice

Response code 303 (“See Also”)

Response header “Content-Location”

Concepts


32

Uniform Interface

Unified set of common operations

Valid for all services, regardless of their resources

Operations & HTTP Methods

Retrieve a representation of a resource: GET

Delete an existing resource: DELETE

Create a new resource:

PUT to a new URI

POST to an existing, factory URI

Modify an existing resource: PUT to an existing URI

Concepts


33

Secondary Operations & HTTP Methods

Retrieve a metadata-only representation: HEAD

Check which methods a resource supports: OPTIONS

Derived Properties

Safety (GET, HEAD)

Idempotence (GET, HEAD, PUT, DELETE)

Concepts


34

Addressability

The service exposes the interesting aspects of its

data set through resources, each with its own URI

There is usually an infinite number of URIs

Clients may consume resources in a way the service

designer did not think of

Principles

/resource

/resource/2

/resource/1


35

Connectedness

Quality of having links

Resource representations are hypermedia

Data

Links (URI) to other resources

Hypermedia as the engine of application state

Empower resource discovery

Principles

/resource

/resource/2

/resource/1


36

Statelessness

Every HTTP request happens in complete isolation

The request holds all info necessary for the server to fulfill it

The server never relies on info from previous requests

HTTP is a stateless protocol by itself

Simpler protocol specification

Simpler clients

Failure conditions eliminated

No client timeout

No client and server out of sync

No request out of scope

Principles


37

Kinds of State

Resource State

Info about the resource

Lives on the server

Application State

Info about the path the client has taken through the application

Lives on the client

Therefore...

A service is stateless if no application state is stored by the

server

Principles


38

Statelessness & Scalability

No session replication

No session affinity

Data replication only when the resource state needs

to be split across multiple machines

Horizontally scalable services

Statelessness & Caching

One cached item per request (URI)

No dependencies on previous requests

Principles

39

Stateless Search Engine Stateful Search Engine

The Resource-Oriented Architecture Principles

Search Form

Initial State

“Jellyfish” “Mice”

Request

Response

Search Form

Initial State

“Jellyfish” “Mice”

Connection

Agenda 40






Security


References

Resource Design

Turning Requirements into Resources

Designing Resource-Oriented

Services 41

Designing RO Services

42

Resource-Oriented Design

Focus on objects, not operations

Extreme object-orientation

Object manipulation happens through resources that respect

the Unified Interface

Instead of defining a new method to a resource, the problem is

solved by defining a new kind of resource

Resource Design

43

Object-Oriented Design Resource-Oriented Design

Designing RO Services Resource Design

subscribes to

Column Reader

Subscription

Column Reader


44

Procedure

1. Figure out the data set

2. Split the data set into resources

3. Name the resources with URIs

4. Expose a subset of the Uniform Interface

5. Design the representations

6. Integrate resources by linking to each other

7. Consider the typical course of events

8. Consider error conditions

Lets try an example...



45

Step 1: Figure out the data set: Domain Overview

Free online classifieds website

Ads are regional

Ads are bound to products

Products belong to categories

Any registered user can comment on ads

Advertisers can publish any number of ads

Shoppers can place orders from within the site

Orders may refer to more than one ad

…



46

Step 1: Figure out the data set: Domain Model



47

Step 2: Split the data set into resources

Ad

Order

Profile

Product

Category

Comment

List of Ads (by search criteria)


Kinds of Resource:

1. A predefined one-off

resource for important

aspects of the app;

2. A resource for every

object exposed through

the service;

3. A resource representing

the results of algorithms

applied to the data set.


48

Step 3: Name the resources with URIs

Single resources

/ad/{id}

/order/{id}

/profile/{id}

/product/{id}

/category/{id}

/ad/{id}/comment/{sequence}

Collection-based resources

/ad ( /ad/?q={keyword} )


URI Encoding:

1. Encode hierarchy into

path variables;

2. Encode combined

scoping information by

using comma or

semicolon;

3. Encode algorithmic

scoping information by

using query variables.


49

Step 4: Expose a subset of the Uniform Interface


Resource GET HEAD POST PUT DELETE

/ad/{id}

/order/{id}

/profile/{id}

/product/{id}

/category/{id}

/ad/{id}/comment/{seq}

/ad


50

Step 5: Design the representations: /ad/{id}


<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>

<head><title>Oakley Jupiter Black </title></head>

<body>

<dl class=“ad”>

<dt>id</dt> <dd>970</dd>

<dt>created</dt> <dd>2010-01-17T14:34:01-03:00</dd>

<dt>description</dt> <dd>…</dd>

<dt>price</dt> <dd>390.00</dd>

<dt>location</dt> <dd>Salvador, BA, BRA</dd>

<dt>advertiser</dt> <dd><a class=“profile” href=“/profile/bgrenn“>Ben Green</a></dd>

<dt>product</dt> <dd><a class=“product” href=“/product/621“>Oakley Jupiter</a>/dd>

<dt>comments</dt> <dd>

<ol class=“comments”>

<li><a class=“comment” href=“/ad/970/comment/1”>Great</a></li>

<li><a class=“comment” href=“/ad/970/comment/2”>Average</a></li>

</ol></dd>

</dl>

</body></html>


51

Step 5: Design the representations: /order/{id}



<head><title>Order 21</title></head>

<body>

<dl class=“order”>



<dt>quantity</dt> <dd>1</dd>

<dt>ad</dt> <dd><a class=“ad” href=“/ad/970”>Oakley Jupiter Black</a></dd>

<dt>shopper</dt> <dd><a class=“profile” href=“/profile/jsmith”>John Smith</a></dd>

</dl>

</body></html>


52

Step 5: Design the representations: /profile/{id}



<head><title>John Smith</title></head>

<body>

<dl class=“profile”>

<dt>id</dt> <dd>jsmith</dd>


<dt>name</dt> <dd>John Smith</dd>

<dt>ads<dt> <dd><ol class=“ads”>

<li><a class=“ad” href=“/ad/88”>Mac Book Pro 13’</a></li>

<li><a class=“ad” href=“/ad/114”>TV LCD Sony 52’</a></li>

</ol></dd>

<dt>orders<dt> <dd><ol class=“orders”>

<li><a class=“order” href=“/order/21”>Order 21</a></li>

</ol></dd>

<dt>comments</dt> <dd></dd>

</dl>

</body></html>


53

Step 5: Design the representations: /product/{id}



<head><title>Oakley Jupiter</title></head>

<body>

<dl class=“product”>




<dt>manufacturer</dt> <dd><a href=“http://www.oakley.com/” >Oakley</a></dd>

<dt>categories</dt> <dd>

<ul class=“categories”>

<li><a class=“category” href=“/category/93”>Eye Wear</a></li>

<li><a class=“category” href=“/category/11”>Surf Fashion</a></li>

</ul></dd>

</dl>

</body></html>


54

Step 5: Design the representations: /category/{id}



<head><title>Eye Wear</title></head>

<body>

<dl class=“category”>




<dt>products</dt> <dd><ul class=“products”>

<li><a class=“product” href=“/product/621”>Oakley Jupiter</a></li>

<li><a class=“product” href=“/product/677”>Oakley Spike</a></li>

<li><a class=“product” href=“/product/741”>Ray Ban Aviator</a></li>

<li><a class=“product” href=“/product/804”>Spy Cooper</a></li>

<li><a class=“product” href=“/product/805”>Spy Lennox</a></li>

</ul></dd>

</dl>

</body></html>


55

Step 5: Design the representations: /ad/{id}/comment/{sequence}



<head><title>Commend 2 on Ad 970</title></head>

<body>

<dl class=“comment”>

<dt>sequence</dt> <dd>2</dd>



<dt>rating</dt> <dd>Average</dd>

<dt>ad</dt> <dd><a class=“ad” href=“/ad/970”>Oakley Jupiter Black</a></dd>

<dt>commentator</dt> <dd><a class=“profile” href=“/profile/agore”>Anna Gore</a></dd>

</dl>

</body></html>


56

Step 5: Design the representations: /ad



<head><title>List of ads by search criteria: Oakley</title></head>

<body>

<ul>

<li><a class=“ad” href=“/ad/970”>Oakley Jupiter Black</a></li>

<li><a class=“ad” href=“/ad/984”>Oakley Spike New</a></li>

<li><a class=“ad” href=“/ad/988”>Oakley Gas Can</a></li>

<li><a class=“ad” href=“/ad/991”>Oakley Flak Jacket</a></li>

<li><a class=“ad” href=“/ad/999”>Oakley Hijinx – Model 2010</a></li>

</ul>

</body></html>


57

Step 6: Integrate resources by linking to each other


Addressable

Connected

Stateless

/ad/{id} /product/{id} /profile/{id}

/ad/{id}/comment/{sequence}

/order/{id}

/category/{id}

/ad

lever of app state


58

Step 7: Consider the typical course of events


Request Response

HTTP Method HTTP Code HTTP Header Entity-Body

GET 200 (“OK”) Content-Type *

Last-Modified **

Representation

304 (“Not Modified”) Last-Modified -

POST 201 (“Created”) Location *** -

PUT 200 (“OK”) - -

DELETE 200 (“OK”) - -

* Content-Type: application/xhtml+xml

** Last-Modified: Mon, 02 Aug 2010 14:10:55 GMT

*** Location: http://example.com/ad/7099


59

Step 8: Consider error conditions

Response

HTTP Code

400 (“Bad Request”)

404 (“Not Found”)

405 (“Method Not Allowed”)

409 (“Conflict”)

415 (“Unsupported Media Type”)

500 (“Internal Server Error”)

503 (“Service Unavailable”)

Entity-Body

It might include a serialized version of the error

Mostly used for debugging purposes


Agenda 60






Security


References

HTTP Headers

HTTP Response Codes

Message Parameterization 61


62

Definition

Informational sticker on the envelope

Message parameter, either input or output

Custom Headers

Most common way of extending HTTP

Client and server ought to agree on the semantics

Guidelines

Do not reinvent an existing header

Do not put things in headers that belong to the entity-body

Follow the naming convention (“X-”, meaning “Extension”)

HTTP Headers


63

Standard Headers

Request

Accept Data format to be used on representations served

Accept-Charset Character set to be used on representations

Accept-Encoding Algorithm to compress representations

Accept-Language Human language in the representations

Authorization Encoded authorization credential

Date The time the request was sent

Host Domain name part of URI (required)

If-Modified-Since Backbone of conditional GET

User-Agent Kind of software making the request

HTTP Headers


64

Standard Headers

Response

Content-Encoding Counterpart to Accept-Encoding

Content-Language Counterpart to Accept-Language

Content-Length Size of the entity-body in bytes

Content-Location Canonical URI of the resource requested

Content-Type Counterpart to Accept. Data format served

Date The time the request was fulfilled (required)

ETag Opaque string to a specific version of a representation

Last-Modified Counterpart to If-Modified-Since

HTTP Headers


65

Standard Headers

Response

Location Multiple interpretations, depending on status code

201 (“Created”)

300 (“Multiple Choices”)

301 (“Moved Permanently”)

302 (“Found”)

303 (“See Other)

307 (”Temporary Redirect”)

HTTP Headers

More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html




66

Definition

Standardized set of meaningful numeric status codes

Communicates the execution result of a given request

Interpretable by service clients without ambiguity

Code Ranges

2xx Success

3xx Redirection

4xx Client-side error

5xx Server-side error

HTTP Response Codes


67

The Bare Minimum

200 (“OK”)

201 (“Created”)

301 (“Moved Permanently”)

400 (“Bad Request”)

404 (“Not Found”)

410 (“Gone”)

409 (“Conflict”)

500 (“Internal Server Error”)

HTTP Response Codes


68

Extra Codes

401 (“Unauthorized”)

403 (“Forbidden”)

405 (“Method Not Allowed”)

415 (“Unsupported Media Type”)

HTTP Response Codes

More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10




Agenda 69






Security


References

Introduction & Use Cases

Proposed Standard

Standardized Service Clients 70


71

Current Scenario

Service description based on textual documentation

Adequate for human consumption only

A more machine-friendly description format is needed



72

Use Cases

Application modeling and visualization

Support for the development of resource modeling tools

Resource relationship analysis and manipulation

Code generation

Automated generation of stub and skeleton code

Code for the manipulation of resource representations

Configuration

Portable format for the configuration of both client and server

Client standardization

General-purpose wrapper for any RESTful service



73

WADL

Web Application Description Language

Syntactic description of RESTful services

XML-based, portable, open format

W3C submission, under review

Elements directly related to ROA

Resource

Representation

Method

Request

Response

Proposed Standard


74

WADL Example (1/3)

Proposed Standard

<?xml version="1.0"?>

<application

xsi:schemaLocation=http://wadl.dev.java.net/2009/02 wadl.xsd

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd=http://www.w3.org/2001/XMLSchema

xmlns:tns="urn:yahoo:yn“

xmlns:yn="urn:yahoo:yn“

xmlns:ya="urn:yahoo:api“

xmlns="http://wadl.dev.java.net/2009/02">

<grammars>

<include href="NewsSearchResponse.xsd"/>

<include href="Error.xsd"/>

</grammars>


75

WADL Example (2/3)

Proposed Standard

<resources base="http://api.search.yahoo.com/NewsSearchService/V1/">

<resource path="newsSearch">

<method name="GET" id="search">

<request>

<param name="appid" type="xsd:string“ style="query" required="true"/>

<param name="query" type="xsd:string“ style="query" required="true"/>

<param name="type" style="query" default="all">

<option value="all"/>

<option value="any"/>

<option value="phrase"/>

</param>

<param name="results" style="query" type="xsd:int" default="10"/>

<param name="start" style="query" type="xsd:int" default="1"/>

<param name="sort" style="query" default="rank">

<option value="rank"/>

<option value="date"/>

</param>

<param name="language" style="query" type="xsd:string"/>

</request>


76

WADL Example (3/3)

Proposed Standard

<response status="200">

<representation mediaType="application/xml“ element="yn:ResultSet"/>

</response>

<response status="400">

<representation mediaType="application/xml“ element="ya:Error"/>

</response>

</method>

</resource>

</resources>

</application>

Agenda 77






Security


References

Authentication & Authorization

Standard Authentication Types

Extended Authentication Types

Security 78

Security

79

Authentication

The process of verifying a claim made by a subject

that it should be allowed to act on behalf of a given

principal

Authorization

The process of verifying that an authenticated subject

has permission to perform certain operations or

access specific resources

Relation

Authentication, therefore, must precede authorization

Authentication & Authorization

Security

80

HTTP Basic Authentication

Challenge-based approach

Credential

Username and password

Algorithm

Combined into a single string

Encoded with Base-64 encoding

Put in the request header “Authorization”


Security

81



GET /resource.html HTTP/1.1

Host: www.example.com

401 Unauthorized

WWW-Authenticate: Basic realm=“Private Data”



Authorization: Basic QWxpYmFiYTpvcGVuIHN1c2FtZQ

200 OK

…

Security

82


Positive

Standard

Simple client and server

Simple credential encoding technique

Negative

Credential transferred as decodable plain text

Solution

Encrypted communication between client and server

HTTPS, SSL (Security Socket Layer)


Security

83

HTTP Digest Authentication

Challenge-based approach

Credential

Request method and path

Four pieces of information from the challenge

Username and password

Client-side nonce

Sequence number

Algorithm

Combined into a single string

Encoded with MD5 encoding

Put in the request header “Authorization”


Security

84





401 Unauthorized

WWW-Authenticate: Digest realm=“Private Data”

qop=“auth”

nonce=“9071c0e6981b49c08d101503a0a4e785”

opaque=“01f2acecddc742599ef15ce3d26d0dec”



Authorization: Digest username=“otaviofff”

realm=“Private Data”

qop=“auth”

nonce=“9071c0e6981b49c08d101503a0a4e785”

opaque=“01f2acecddc742599ef15ce3d26d0dec”

uri=“/resource.html”

nc=“00000001”

cnonce =“dbca690880a741538651900d22b9e6f4”

response=“801eb79ddff844888533a2ca38c7decc”

Security

85


Positive

Standard

Secure even over unencrypted HTTP

Password not stored in the server

Negative

More complex client and server

The client cannot avoid the challenge. Always 2 requests

Man-in-the-middle might tamper the representation sent

Solution

Use qop=“auth-int”, instead of “auth”

Thus, the entity-body in included in the credential


Security

86

WSSE Username Token

Ported from SOAP to HTTP

Based on WS-Security Extension, Username Token

Based on challenge as well

Credential

Password Digest

Client-side nonce

Creation date

Algorithm

Client generates a nonce

Then hashed their password along with the nonce and date

Encodes with Base-64 encoding


Security

87

WSSE Username Token




401 Unauthorized

WWW-Authenticate: WSSE realm=“Private Data”, profile=“UsernameToken”



Authorization: WSSE profile=“UserToken”

PasswordDigest=“Private Data”

Nonce=“9071c0e6981b49c08d101503a0a4e785”

Created=“2010-08-03T09:45:08Z”

200 OK

…

Security

88

WSSE Username Token

Positive

Secure even over unencrypted HTTP

Password not transferred over the network

Negative

The server must store the password as plain text

Solution

The complexity of Digest is meat to overcome this limitation


Security

89

New Approaches

API Key

OAuth


Agenda 90






Security


References

Java

PHP

Python

Ruby

Directory of Frameworks 91


92

Restlet

http://www.restlet.org/

JBoss REST Easy

http://www.jboss.org/resteasy/

Glassfish Jersey https://jersey.dev.java.net/

Java

http://www.restlet.org/

http://www.jboss.org/resteasy/

https://jersey.dev.java.net/


93

SerfJ http://serfj.sourceforge.net/

Play http://www.playframework.org/

Java

http://serfj.sourceforge.net/

http://www.playframework.org/


94

Zend Framework (Zend_Rest)

http://framework.zend.com/

Recess http://recessframework.org/

Tonic

http://tonic.sourceforge.net/

PHP

http://framework.zend.com/

http://www.recessframework.org/

http://tonic.sourceforge.net/


95

Django

http://www.djangoproject.com/

Cherry Py http://www.cherrypy.org/

Python

http://www.djangoproject.com/

http://www.cherrypy.org/


96

Rails

http://www.rubyonrails.org/

Sinatra http://www.sinatrarb.com/

Ruby

http://www.rubyonrails.org/

http://www.sinatrarb.com/

Agenda 97






Security


References

Books & Specs

References 98

References

99

Books & Specs

RESTful Web Services By Leonard Richardson, Sam Ruby

O’Reilly, 2007

Hypertext Transfer Protocol HTTP/1.1 By W3C, 1999

http://www.w3.org/Protocols/rfc2616/rfc2616.html

http://www.w3.org/Protocols/rfc2616/rfc2616.html

Agenda 100






Security


References

Icons by David Lanham / http://dlanham.com/

http://dlanham.com/

Technology

API Design Workshop