API Design Workshop

API DESIGNAugust 2010 Otavio Ferreira (@otaviofff)

Agenda2  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References

3 The Programmable Web  HTTP: Documents in Envelopes  Method Information  Scoping Information  The Competing Architectures  The Human Web  Technologies

The Programmable Web HTTP: Documents in Envelopes4  HTTP  Hypertext Transfer Protocol  Application layer, document-based, request-response protocol for distributed, collaborative, hypermedia information systems  Foundation of the Web  Strict envelop structure

The Programmable Web HTTP: Documents in Envelopes5  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

The Programmable Web HTTP: Documents in Envelopes6  HTTP Request (2/4) The HTTP method GET /index.html HTTP/1.1 Indicates how the client Host: www.oreilly.com expects the server to User-Agent: Mozilla/5.0 process this envelope. Accept: text/xml, text/html, application/xml, ... Accept-Language: us, en The path Accept-Encoding: gzip, deflate Indicates the execution Accept-Charset: ISO-8859, UTF-8 scope. Keep-Alive: 300 Connection: Keep-Alive The HTTP version Indicates the protocol version to be considered by the server while processing the envelope.

The Programmable Web HTTP: Documents in Envelopes7  HTTP Request (3/4) The request headers GET /index.html HTTP/1.1 Key-value pairs that act as Host: www.oreilly.com informational stickers User-Agent: Mozilla/5.0 slapped onto the envelope. Accept: text/xml, text/html, application/xml, ... Accept-Language: us, en Parameters that affect the Accept-Encoding: gzip, deflate way the server processes Accept-Charset: ISO-8859, UTF-8 the request. Keep-Alive: 300 Connection: Keep-Alive There is a standard list of headers defined in the protocol specification.

The Programmable Web HTTP: Documents in Envelopes8  HTTP Request (4/4) The entity body GET /index.html HTTP/1.1 Document inside the Host: www.oreilly.com envelope. Object to be User-Agent: Mozilla/5.0 processed by the server. Accept: text/xml, text/html, application/xml, ... Accept-Language: us, en This particular envelope Accept-Encoding: gzip, deflate has no entity, which means Accept-Charset: ISO-8859, UTF-8 the envelope is empty. Keep-Alive: 300 Connection: Keep-Alive This is typical for a GET request, where all the information needed is in the path and the headers.

The Programmable Web HTTP: Documents in Envelopes9  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 Connection: Keep-Alive <!DOCTYPE html PUBLIC “...”> <html>...</html>

The Programmable Web HTTP: Documents in Envelopes10  HTTP Response (2/4) The HTTP response code HTTP/1.1 200 OK Numeric code that tells the Date: Mon 26 Jul 2010 15:35:55 GMT client whether the request Server: Apache succeeded. Last-Modified: Fri 23 Jul 2010 14:01:13 GMT Accept-Ranges: bytes Hence, it indicates how the Content-Length: 43302 client should regard this Content-Type: text/html envelope and its content. X-Cache: MISS from www.oreilly.com Keep-Alive: timeout=15, max=1000 There is a standard list of Connection: Keep-Alive response codes defined in the protocol specification. <!DOCTYPE html PUBLIC “...”> <html>...</html>

The Programmable Web HTTP: Documents in Envelopes11  HTTP Response (3/4) The response headers HTTP/1.1 200 OK As with the request Date: Mon 26 Jul 2010 15:35:55 GMT headers, these are key- Server: Apache value pairs that act as Last-Modified: Fri 23 Jul 2010 14:01:13 GMT informational stickers Accept-Ranges: bytes slapped onto the envelope. Content-Length: 43302 Content-Type: text/html Detail the execution X-Cache: MISS from www.oreilly.com results, and describe the Keep-Alive: timeout=15, max=1000 entity returned, if any. Connection: Keep-Alive <!DOCTYPE html PUBLIC “...”> <html>...</html>

The Programmable Web HTTP: Documents in Envelopes12  HTTP Response (4/4) The entity body HTTP/1.1 200 OK Again, the document inside Date: Mon 26 Jul 2010 15:35:55 GMT the envelope. This entity is Server: Apache often referred to as Last-Modified: Fri 23 Jul 2010 14:01:13 GMT representation. Accept-Ranges: bytes Content-Length: 43302 It is the fulfillment of the Content-Type: text/html request message sent by X-Cache: MISS from www.oreilly.com the client. Keep-Alive: timeout=15, max=1000 Connection: Keep-Alive The encoding applied to the entity is presented by <!DOCTYPE html PUBLIC “...”> the Content-Type header. <html>...</html>

The Programmable Web Method Information13  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

The Programmable Web Method Information14  Other Approaches  Application-specific method names  Method set in the request path or entity body 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 Method Information15 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 Scoping Information16  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

The Programmable Web Scoping Information17  Other Approaches  Application-specific path locations  Scope set in the request entity body 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 Scoping Information18 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 The Competing Architectures19  Architectural Decisions 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 The Human Web20  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 Programmable Web Technologies21  Classification  Technologies do not classify services  Architectural styles do  Technologies  HTTP  URI  XML-RPC  SOAP  WS-*  WSDL, WADL  XML, JSON, XHTML, RDF, ...

23 The Resource-Oriented Architecture  Introduction  Concepts  Principles

The Resource-Oriented Architecture Introduction24  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

The Resource-Oriented Architecture Introduction25  Concepts  Resource  Representation  Uniform Identifier  Uniform Interface  Principles  Addressability  Connectedness  Statelessness

The Resource-Oriented Architecture Concepts26  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

The Resource-Oriented Architecture Concepts27  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 – Architecture of the World Wide Web, Volume One, 2004, W3C

The Resource-Oriented Architecture Concepts28  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) { "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 Concepts29  Deciding between Representations  Multiple URIs  HTTP header ”Accept”  HTTP header “Accept-Language”  Other HTTP request metadata

The Resource-Oriented Architecture Concepts30  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

The Resource-Oriented Architecture Concepts31  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”

The Resource-Oriented Architecture Concepts32  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

The Resource-Oriented Architecture Concepts33  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)

The Resource-Oriented Architecture Principles34  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 /resource/1 /resource /resource/2

The Resource-Oriented Architecture Principles35  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 /resource/1 /resource /resource/2

The Resource-Oriented Architecture Principles36  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

The Resource-Oriented Architecture Principles37  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

The Resource-Oriented Architecture Principles38  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

The Resource-Oriented Architecture Principles39 Stateless Search Engine Stateful Search Engine Search Form Initial State “Mice” “Jellyfish” “Mice” “Jellyfish” Initial State Search Form Request Response Connection

41 Designing Resource-Oriented Services  Resource Design  Turning Requirements into Resources

Designing RO Services Resource Design42  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

Designing RO Services Resource Design43 Object-Oriented Design Resource-Oriented Design Subscription subscribes to Reader Column Reader Column

Designing RO Services Turning Requirements into Resources44  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...

Designing RO Services Turning Requirements into Resources45  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  …

Designing RO Services Turning Requirements into Resources46  Step 1: Figure out the data set: Domain Model

Designing RO Services Turning Requirements into Resources47  Step 2: Split the data set into resources  Ad Kinds of Resource: 1. A predefined one-off  Order resource for important  Profile aspects of the app; 2. A resource for every  Product object exposed through the service;  Category 3. A resource representing  Comment the results of algorithms applied to the data set.  List of Ads (by search criteria)

Designing RO Services Turning Requirements into Resources48  Step 3: Name the resources with URIs  Single resources URI Encoding:  /ad/{id} 1. Encode hierarchy into path variables;  /order/{id} 2. Encode combined  /profile/{id} scoping information by  /product/{id} using comma or semicolon;  /category/{id} 3. Encode algorithmic  /ad/{id}/comment/{sequence} scoping information by using query variables.  Collection-based resources  /ad ( /ad/?q={keyword} )

Designing RO Services Turning Requirements into Resources49  Step 4: Expose a subset of the Uniform InterfaceResource GET HEAD POST PUT DELETE/ad/{id}/order/{id}/profile/{id}/product/{id}/category/{id}/ad/{id}/comment/{seq}/ad

Designing RO Services Turning Requirements into Resources50  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>

Designing RO Services Turning Requirements into Resources51  Step 5: Design the representations: /order/{id} <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 Turning Requirements into Resources52  Step 5: Design the representations: /profile/{id} <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 Turning Requirements into Resources53  Step 5: Design the representations: /product/{id} <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 Turning Requirements into Resources54  Step 5: Design the representations: /category/{id} <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 Turning Requirements into Resources55  Step 5: Design the representations: /ad/{id}/comment/{sequence} <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 Turning Requirements into Resources56  Step 5: Design the representations: /ad <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 Turning Requirements into Resources57  Step 6: Integrate resources by linking to each other /ad/{id}/comment/{sequence}  Addressable  Connected lever of app state  Stateless /profile/{id} /ad/{id} /product/{id} /category/{id} /order/{id} /ad

Designing RO Services Turning Requirements into Resources58  Step 7: Consider the typical course of events Request Response HTTP Method HTTP Code HTTP Header Entity-Body GET 200 (“OK”) Content-Type * Representation Last-Modified ** 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 Turning Requirements into Resources59  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

61 Message Parameterization  HTTP Headers  HTTP Response Codes

Message Parameterization HTTP Headers62  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”)

Message Parameterization HTTP Headers63  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

Message Parameterization HTTP Headers64  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

Message Parameterization HTTP Headers65  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”) More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14

Message Parameterization HTTP Response Codes66  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

Message Parameterization HTTP Response Codes67  The Bare Minimum  200 (“OK”)  201 (“Created”)  301 (“Moved Permanently”)  400 (“Bad Request”)  404 (“Not Found”)  410 (“Gone”)  409 (“Conflict”)  500 (“Internal Server Error”)

Message Parameterization HTTP Response Codes68  Extra Codes  401 (“Unauthorized”)  403 (“Forbidden”)  405 (“Method Not Allowed”)  415 (“Unsupported Media Type”) More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10

70 Standardized Service Clients  Introduction & Use Cases  Proposed Standard

Standardized Service Clients Introduction & Use Cases71  Current Scenario  Service description based on textual documentation  Adequate for human consumption only  A more machine-friendly description format is needed

Standardized Service Clients Introduction & Use Cases72  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

Standardized Service Clients Proposed Standard73  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

Standardized Service Clients Proposed Standard74  WADL Example (1/3) <?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 Proposed Standard75  WADL Example (2/3) <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 Proposed Standard76  WADL Example (3/3) <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>

78 Security  Authentication & Authorization  Standard Authentication Types  Extended Authentication Types

Security Authentication & Authorization79  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

Security Standard Authentication Types80  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 Standard Authentication Types81  HTTP Basic Authentication 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 Standard Authentication Types82  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)

Security Standard Authentication Types83  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 Standard Authentication Types84  HTTP Digest Authentication 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 Standard Authentication Types85  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

Security Extended Authentication Types86  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 Extended Authentication Types87  WSSE Username Token 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 Extended Authentication Types88  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 Extended Authentication Types89  New Approaches  API Key  OAuth

91 Directory of Frameworks  Java  PHP  Python  Ruby

Directory of Frameworks Java92  Restlet http://www.restlet.org/  JBoss REST Easy http://www.jboss.org/resteasy/  Glassfish Jersey https://jersey.dev.java.net/

Directory of Frameworks Java93  SerfJ http://serfj.sourceforge.net/  Play http://www.playframework.org/

Directory of Frameworks PHP94  Zend Framework (Zend_Rest) http://framework.zend.com/  Recess http://recessframework.org/  Tonic http://tonic.sourceforge.net/

Directory of Frameworks Python95  Django http://www.djangoproject.com/  Cherry Py http://www.cherrypy.org/

Directory of Frameworks Ruby96  Rails http://www.rubyonrails.org/  Sinatra http://www.sinatrarb.com/

98 References  Books & Specs

References Books & Specs99 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

Agenda100  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/

API Design Workshop

by Otavio Ferreira

Accessibility

Categories

Upload Details

Usage Rights

2 Embeds 2

Statistics

API Design Workshop Presentation Transcript

http://www.linkedin.com	1
http://www.slashdocs.com	1