api design workshop
Post on 10-May-2015
1.468 Views
Preview:
DESCRIPTION
TRANSCRIPT
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
The Programmable Web
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
HTTP: Documents in Envelopes
The Programmable Web
5
HTTP Request (1/4)
HTTP: Documents in Envelopes
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
The Programmable Web
6
HTTP Request (2/4)
HTTP: Documents in Envelopes
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
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.
The Programmable Web
7
HTTP Request (3/4)
HTTP: Documents in Envelopes
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
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.
The Programmable Web
8
HTTP Request (4/4)
HTTP: Documents in Envelopes
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
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.
The Programmable Web
9
HTTP Response (1/4)
HTTP: Documents in Envelopes
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
Connection: Keep-Alive
<!DOCTYPE html PUBLIC “...”>
<html>...</html>
The Programmable Web
10
HTTP Response (2/4)
HTTP: Documents in Envelopes
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
Connection: Keep-Alive
<!DOCTYPE html PUBLIC “...”>
<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.
The Programmable Web
11
HTTP Response (3/4)
HTTP: Documents in Envelopes
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
Connection: Keep-Alive
<!DOCTYPE html PUBLIC “...”>
<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.
The Programmable Web
12
HTTP Response (4/4)
HTTP: Documents in Envelopes
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
Connection: Keep-Alive
<!DOCTYPE html PUBLIC “...”>
<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.
The Programmable Web
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
The Programmable Web
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
Host: api.flickr.com
The Programmable Web
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>
The Programmable Web
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
The Programmable Web
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
Host: api.flickr.com
GET /services/rest/?method=flickr.photos.delete&api_key={...}&photo_id={...} HTTP/1.1
Host: api.flickr.com
The Programmable Web
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>
The Programmable Web
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
The Programmable 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
The Programmable 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
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
References
Introduction
Concepts
Principles
The Resource-Oriented
Architecture 23
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
25
Concepts
Resource
Representation
Uniform Identifier
Uniform Interface
Principles
Addressability
Connectedness
Statelessness
Introduction
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
}
The Resource-Oriented Architecture
29
Deciding between Representations
Multiple URIs
HTTP header ”Accept”
HTTP header “Accept-Language”
Other HTTP request metadata
Concepts
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Resource-Oriented Architecture
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
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
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
Designing RO Services
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...
Turning Requirements into Resources
Designing RO Services
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
…
Turning Requirements into Resources
Designing RO Services
46
Step 1: Figure out the data set: Domain Model
Turning Requirements into Resources
Designing RO Services
47
Step 2: Split the data set into resources
Ad
Order
Profile
Product
Category
Comment
List of Ads (by search criteria)
Turning Requirements into Resources
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.
Designing RO Services
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} )
Turning Requirements into Resources
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.
Designing RO Services
49
Step 4: Expose a subset of the Uniform Interface
Turning Requirements into Resources
Resource GET HEAD POST PUT DELETE
/ad/{id}
/order/{id}
/profile/{id}
/product/{id}
/category/{id}
/ad/{id}/comment/{seq}
/ad
Designing RO Services
50
Step 5: Design the representations: /ad/{id}
Turning Requirements into Resources
<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>
Designing RO Services
51
Step 5: Design the representations: /order/{id}
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<head><title>Order 21</title></head>
<body>
<dl class=“order”>
<dt>id</dt> <dd>21</dd>
<dt>created</dt> <dd>2010-02-01T13:11:59-02:00</dd>
<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>
Designing RO Services
52
Step 5: Design the representations: /profile/{id}
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<head><title>John Smith</title></head>
<body>
<dl class=“profile”>
<dt>id</dt> <dd>jsmith</dd>
<dt>created</dt> <dd>2008-02-25T07:38:40-03:00</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>
Designing RO Services
53
Step 5: Design the representations: /product/{id}
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<head><title>Oakley Jupiter</title></head>
<body>
<dl class=“product”>
<dt>id</dt> <dd>621</dd>
<dt>created</dt> <dd>2009-11-21T06:59:00-03:00</dd>
<dt>description</dt> <dd>…</dd>
<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>
Designing RO Services
54
Step 5: Design the representations: /category/{id}
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<head><title>Eye Wear</title></head>
<body>
<dl class=“category”>
<dt>id</dt> <dd>93</dd>
<dt>created</dt> <dd>2008-10-30T16:19:10-03:00</dd>
<dt>description</dt> <dd>…</dd>
<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>
Designing RO Services
55
Step 5: Design the representations: /ad/{id}/comment/{sequence}
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<head><title>Commend 2 on Ad 970</title></head>
<body>
<dl class=“comment”>
<dt>sequence</dt> <dd>2</dd>
<dt>created</dt> <dd>2010-03-11T14:15:59-02:00</dd>
<dt>description</dt> <dd>…</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>
Designing RO Services
56
Step 5: Design the representations: /ad
Turning Requirements into Resources
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
<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>
Designing RO Services
57
Step 6: Integrate resources by linking to each other
Turning Requirements into Resources
Addressable
Connected
Stateless
/ad/{id} /product/{id} /profile/{id}
/ad/{id}/comment/{sequence}
/order/{id}
/category/{id}
/ad
lever of app state
Designing RO Services
58
Step 7: Consider the typical course of events
Turning Requirements into Resources
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
Designing RO Services
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
Turning Requirements into Resources
Agenda 60
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
References
HTTP Headers
HTTP Response Codes
Message Parameterization 61
Message Parameterization
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
Message Parameterization
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
Message Parameterization
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
Message Parameterization
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
Message Parameterization
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
Message Parameterization
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
Message Parameterization
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
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
References
Introduction & Use Cases
Proposed Standard
Standardized Service Clients 70
Standardized Service Clients
71
Current Scenario
Service description based on textual documentation
Adequate for human consumption only
A more machine-friendly description format is needed
Introduction & Use Cases
Standardized Service Clients
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
Introduction & Use Cases
Standardized Service Clients
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
Standardized Service Clients
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>
Standardized Service Clients
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>
Standardized Service Clients
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
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
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”
Standard Authentication Types
Security
81
HTTP Basic Authentication
Standard Authentication Types
GET /resource.html HTTP/1.1
Host: www.example.com
401 Unauthorized
WWW-Authenticate: Basic realm=“Private Data”
GET /resource.html HTTP/1.1
Host: www.example.com
Authorization: Basic QWxpYmFiYTpvcGVuIHN1c2FtZQ
200 OK
…
Security
82
HTTP Basic Authentication
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)
Standard Authentication Types
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”
Standard Authentication Types
Security
84
HTTP Digest Authentication
Standard Authentication Types
GET /resource.html HTTP/1.1
Host: www.example.com
401 Unauthorized
WWW-Authenticate: Digest realm=“Private Data”
qop=“auth”
nonce=“9071c0e6981b49c08d101503a0a4e785”
opaque=“01f2acecddc742599ef15ce3d26d0dec”
GET /resource.html HTTP/1.1
Host: www.example.com
Authorization: Digest username=“otaviofff”
realm=“Private Data”
qop=“auth”
nonce=“9071c0e6981b49c08d101503a0a4e785”
opaque=“01f2acecddc742599ef15ce3d26d0dec”
uri=“/resource.html”
nc=“00000001”
cnonce =“dbca690880a741538651900d22b9e6f4”
response=“801eb79ddff844888533a2ca38c7decc”
Security
85
HTTP Digest Authentication
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
Standard Authentication Types
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
Extended Authentication Types
Security
87
WSSE Username Token
Extended Authentication Types
GET /resource.html HTTP/1.1
Host: www.example.com
401 Unauthorized
WWW-Authenticate: WSSE realm=“Private Data”, profile=“UsernameToken”
GET /resource.html HTTP/1.1
Host: www.example.com
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
Extended Authentication Types
Security
89
New Approaches
API Key
OAuth
Extended Authentication Types
Agenda 90
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
References
Java
PHP
Python
Ruby
Directory of Frameworks 91
Directory of Frameworks
92
Restlet
http://www.restlet.org/
JBoss REST Easy
http://www.jboss.org/resteasy/
Glassfish Jersey https://jersey.dev.java.net/
Java
Directory of Frameworks
93
SerfJ http://serfj.sourceforge.net/
Play http://www.playframework.org/
Java
Directory of Frameworks
94
Zend Framework (Zend_Rest)
http://framework.zend.com/
Recess http://recessframework.org/
Tonic
http://tonic.sourceforge.net/
PHP
Directory of Frameworks
95
Django
http://www.djangoproject.com/
Cherry Py http://www.cherrypy.org/
Python
Directory of Frameworks
96
Rails
http://www.rubyonrails.org/
Sinatra http://www.sinatrarb.com/
Ruby
Agenda 97
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
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
Agenda 100
The Programmable Web
The Resource-Oriented Architecture
Designing Resource-Oriented Services
Message Parameterization
Standardized Service Clients
Security
Directory of Frameworks
References
Icons by David Lanham / http://dlanham.com/
top related