API Design Workshop

  • 1,405 views
Uploaded on

This workshop aims at empowering development teams so that they can build their own RESTful API.

This workshop aims at empowering development teams so that they can build their own RESTful API.

More in: Technology , Business
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
1,405
On Slideshare
0
From Embeds
0
Number of Embeds
2

Actions

Shares
Downloads
14
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. API DESIGNAugust 2010 Otavio Ferreira (@otaviofff)
  • 2. Agenda2  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 3. 3 The Programmable Web  HTTP: Documents in Envelopes  Method Information  Scoping Information  The Competing Architectures  The Human Web  Technologies
  • 4. 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
  • 5. 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
  • 6. 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.
  • 7. 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.
  • 8. 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.
  • 9. 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>
  • 10. 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>
  • 11. 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>
  • 12. 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>
  • 13. 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
  • 14. 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
  • 15. 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>
  • 16. 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
  • 17. 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
  • 18. 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>
  • 19. 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
  • 20. 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
  • 21. 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, ...
  • 22. Agenda22  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 23. 23 The Resource-Oriented Architecture  Introduction  Concepts  Principles
  • 24. 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
  • 25. The Resource-Oriented Architecture Introduction25  Concepts  Resource  Representation  Uniform Identifier  Uniform Interface  Principles  Addressability  Connectedness  Statelessness
  • 26. 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
  • 27. 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
  • 28. 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 }
  • 29. The Resource-Oriented Architecture Concepts29  Deciding between Representations  Multiple URIs  HTTP header ”Accept”  HTTP header “Accept-Language”  Other HTTP request metadata
  • 30. 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
  • 31. 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”
  • 32. 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
  • 33. 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)
  • 34. 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
  • 35. 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
  • 36. 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
  • 37. 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
  • 38. 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
  • 39. 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
  • 40. Agenda40  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 41. 41 Designing Resource-Oriented Services  Resource Design  Turning Requirements into Resources
  • 42. 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
  • 43. Designing RO Services Resource Design43 Object-Oriented Design Resource-Oriented Design Subscription subscribes to Reader Column Reader Column
  • 44. 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...
  • 45. 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  …
  • 46. Designing RO Services Turning Requirements into Resources46  Step 1: Figure out the data set: Domain Model
  • 47. 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)
  • 48. 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} )
  • 49. 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
  • 50. 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>
  • 51. 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>
  • 52. 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>
  • 53. 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>
  • 54. 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>
  • 55. 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>
  • 56. 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>
  • 57. 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
  • 58. 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
  • 59. 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
  • 60. Agenda60  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 61. 61 Message Parameterization  HTTP Headers  HTTP Response Codes
  • 62. 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”)
  • 63. 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
  • 64. 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
  • 65. 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
  • 66. 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
  • 67. 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”)
  • 68. 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
  • 69. Agenda69  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 70. 70 Standardized Service Clients  Introduction & Use Cases  Proposed Standard
  • 71. 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
  • 72. 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
  • 73. 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
  • 74. 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>
  • 75. 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>
  • 76. 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>
  • 77. Agenda77  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 78. 78 Security  Authentication & Authorization  Standard Authentication Types  Extended Authentication Types
  • 79. 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
  • 80. 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”
  • 81. 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 …
  • 82. 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)
  • 83. 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”
  • 84. 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”
  • 85. 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
  • 86. 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
  • 87. 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 …
  • 88. 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
  • 89. Security Extended Authentication Types89  New Approaches  API Key  OAuth
  • 90. Agenda90  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 91. 91 Directory of Frameworks  Java  PHP  Python  Ruby
  • 92. Directory of Frameworks Java92  Restlet http://www.restlet.org/  JBoss REST Easy http://www.jboss.org/resteasy/  Glassfish Jersey https://jersey.dev.java.net/
  • 93. Directory of Frameworks Java93  SerfJ http://serfj.sourceforge.net/  Play http://www.playframework.org/
  • 94. Directory of Frameworks PHP94  Zend Framework (Zend_Rest) http://framework.zend.com/  Recess http://recessframework.org/  Tonic http://tonic.sourceforge.net/
  • 95. Directory of Frameworks Python95  Django http://www.djangoproject.com/  Cherry Py http://www.cherrypy.org/
  • 96. Directory of Frameworks Ruby96  Rails http://www.rubyonrails.org/  Sinatra http://www.sinatrarb.com/
  • 97. Agenda97  The Programmable Web  The Resource-Oriented Architecture  Designing Resource-Oriented Services  Message Parameterization  Standardized Service Clients  Security  Directory of Frameworks  References
  • 98. 98 References  Books & Specs
  • 99. 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
  • 100. 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/