SlideShare a Scribd company logo
1 of 100
Download to read offline
API DESIGN
August 2010   Otavio Ferreira (@otaviofff)
Agenda
2


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


       HTTP Request (1/4)

    GET /index.html HTTP/1.1
    Host: www.oreilly.com
    User-Agent: Mozilla/5.0
    Accept: text/xml, text/html, application/xml, ...
    Accept-Language: us, en
    Accept-Encoding: gzip, deflate
    Accept-Charset: ISO-8859, UTF-8
    Keep-Alive: 300
    Connection: Keep-Alive
The Programmable Web
     HTTP: Documents in Envelopes
6


       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 Envelopes
7


       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 Envelopes
8


       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 Envelopes
9


       HTTP Response (1/4)

    HTTP/1.1 200 OK
    Date: Mon 26 Jul 2010 15:35:55 GMT
    Server: Apache
    Last-Modified: Fri 23 Jul 2010 14:01:13 GMT
    Accept-Ranges: bytes
    Content-Length: 43302
    Content-Type: text/html
    X-Cache: MISS from www.oreilly.com
    Keep-Alive: timeout=15, max=1000
    Connection: Keep-Alive

    <!DOCTYPE html PUBLIC “...”>
    <html>...</html>
The Programmable Web
      HTTP: Documents in Envelopes
10


        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 Envelopes
11


        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 Envelopes
12


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


          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 Information
15




        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 Information
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
The Programmable Web
       Scoping Information
17


          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 Information
18




        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 Architectures
19


        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 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 Programmable Web
     Technologies
21


        Classification
          Technologies do not classify services
          Architectural styles do

        Technologies
          HTTP
          URI

          XML-RPC

          SOAP

          WS-*

          WSDL, WADL

          XML, JSON, XHTML, RDF, ...
Agenda
22


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

      Principles
The Resource-Oriented Architecture
     Introduction
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
The Resource-Oriented Architecture
     Introduction
25


        Concepts
          Resource
          Representation

          Uniform Identifier

          Uniform Interface

        Principles
          Addressability
          Connectedness

          Statelessness
The Resource-Oriented Architecture
     Concepts
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
The Resource-Oriented Architecture
     Concepts
27


        Identifying Resources
            If another party [users] might reasonably want to...
                Create a hypertext link to it
                Make or refute assertions about it
                Retrieve or cache a representation of it
                Include all or part of it by reference into another representation
                Annotate it
                Perform other operations on it
            Then, it has to be a resource

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

             {
                 "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
     Concepts
29


        Deciding between Representations
          Multiple URIs
          HTTP header ”Accept”

          HTTP header “Accept-Language”

          Other HTTP request metadata
The Resource-Oriented Architecture
     Concepts
30


        Uniform Identifier
          URI – Uniform Resource Identifier
          It is the name and address of a resource

          Each resource has to have at least one URI

        Uniform Identifier Examples
          http://example.com/map/bra/ce/fortaleza
          http://example.com/wiki/dog

          http://example.com/search/dog

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

          http://example.com/discography/coldplay

          http://example.com/user/alice/humor
The Resource-Oriented Architecture
     Concepts
31


        Analyzing Uniform Identifiers
          URIs should be descriptive
          URIs should have clear, intuitive structure and notation

          URIs should vary in predictable ways

          Clients may create their own entry points into services

        Constraints
          Every URI designates one Resource
          Every Resource might be designated by various URIs

          Defining a canonical URI is a best practice
                Response code 303 (“See Also”)
                Response header “Content-Location”
The Resource-Oriented Architecture
     Concepts
32


        Uniform Interface
          Unified set of common operations
          Valid for all services, regardless of their resources

        Operations & HTTP Methods
          Retrieve a representation of a resource: GET
          Delete an existing resource: DELETE

          Create a new resource:
                PUT to a new URI
                POST to an existing, factory URI
            Modify an existing resource: PUT to an existing URI
The Resource-Oriented Architecture
     Concepts
33


        Secondary Operations & HTTP Methods
          Retrieve a metadata-only representation: HEAD
          Check which methods a resource supports: OPTIONS

        Derived Properties
          Safety (GET, HEAD)
          Idempotence (GET, HEAD, PUT, DELETE)
The Resource-Oriented Architecture
     Principles
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




                                           /resource/1
             /resource

                             /resource/2
The Resource-Oriented Architecture
     Principles
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




                                                   /resource/1
                 /resource

                                     /resource/2
The Resource-Oriented Architecture
     Principles
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
The Resource-Oriented Architecture
     Principles
37


        Kinds of State
            Resource State
                Info about the resource
                Lives on the server
            Application State
                Info about the path the client has taken through the application
                Lives on the client
            Therefore...
                A service is stateless if no application state is stored by the
                 server
The Resource-Oriented Architecture
     Principles
38


        Statelessness & Scalability
          No session replication
          No session affinity

          Data replication only when the resource state needs
           to be split across multiple machines
          Horizontally scalable services

        Statelessness & Caching
          One cached item per request (URI)
          No dependencies on previous requests
The Resource-Oriented Architecture
     Principles
39



     Stateless Search Engine                    Stateful Search Engine

                 Search Form                                Initial State




       “Mice”                     “Jellyfish”     “Mice”                    “Jellyfish”



                  Initial State                            Search Form

                Request
                Response                                   Connection
Agenda
40


        The Programmable Web
        The Resource-Oriented Architecture
        Designing Resource-Oriented Services
        Message Parameterization
        Standardized Service Clients
        Security
        Directory of Frameworks
        References
41
     Designing Resource-Oriented
     Services
      Resource Design
      Turning Requirements into Resources
Designing RO Services
     Resource Design
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
Designing RO Services
     Resource Design
43



     Object-Oriented Design              Resource-Oriented Design

                                                    Subscription




                subscribes to



       Reader                   Column     Reader                  Column
Designing RO Services
     Turning Requirements into Resources
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...
Designing RO Services
     Turning Requirements into Resources
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

          …
Designing RO Services
     Turning Requirements into Resources
46


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


        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 Resources
48


        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 Resources
49


          Step 4: Expose a subset of the Uniform Interface

Resource                 GET     HEAD       POST   PUT   DELETE
/ad/{id}
/order/{id}
/profile/{id}
/product/{id}
/category/{id}
/ad/{id}/comment/{seq}
/ad
Designing RO Services
     Turning Requirements into Resources
50


        Step 5: Design the representations: /ad/{id}
     <html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”>
     <head><title>Oakley Jupiter Black </title></head>
     <body>
     <dl class=“ad”>
     <dt>id</dt>           <dd>970</dd>
     <dt>created</dt>      <dd>2010-01-17T14:34:01-03:00</dd>
     <dt>description</dt> <dd>…</dd>
     <dt>price</dt>        <dd>390.00</dd>
     <dt>location</dt>     <dd>Salvador, BA, BRA</dd>
     <dt>advertiser</dt>   <dd><a class=“profile” href=“/profile/bgrenn“>Ben Green</a></dd>
     <dt>product</dt>      <dd><a class=“product” href=“/product/621“>Oakley Jupiter</a>/dd>
     <dt>comments</dt> <dd>
                           <ol class=“comments”>
                              <li><a class=“comment” href=“/ad/970/comment/1”>Great</a></li>
                              <li><a class=“comment” href=“/ad/970/comment/2”>Average</a></li>
                           </ol></dd>
     </dl>
     </body></html>
Designing RO Services
     Turning Requirements into Resources
51


        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 Resources
52


        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 Resources
53


        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 Resources
54


        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 Resources
55


        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 Resources
56


        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 Resources
57


        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 Resources
58


          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 Resources
59


        Step 8: Consider error conditions
            Response
                HTTP Code
                     400 (“Bad Request”)
                     404 (“Not Found”)
                     405 (“Method Not Allowed”)
                     409 (“Conflict”)
                     415 (“Unsupported Media Type”)
                     500 (“Internal Server Error”)
                     503 (“Service Unavailable”)
                Entity-Body
                     It might include a serialized version of the error
                     Mostly used for debugging purposes
Agenda
60


        The Programmable Web
        The Resource-Oriented Architecture
        Designing Resource-Oriented Services
        Message Parameterization
        Standardized Service Clients
        Security
        Directory of Frameworks
        References
61   Message Parameterization
      HTTP Headers
      HTTP Response Codes
Message Parameterization
     HTTP Headers
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”)
Message Parameterization
     HTTP Headers
63


        Standard Headers
            Request
                Accept  Data format to be used on representations served
                Accept-Charset  Character set to be used on representations
                Accept-Encoding  Algorithm to compress representations
                Accept-Language  Human language in the representations
                Authorization  Encoded authorization credential
                Date  The time the request was sent
                Host  Domain name part of URI (required)
                If-Modified-Since  Backbone of conditional GET
                User-Agent  Kind of software making the request
Message Parameterization
     HTTP Headers
64


        Standard Headers
            Response
                Content-Encoding  Counterpart to Accept-Encoding
                Content-Language  Counterpart to Accept-Language
                Content-Length  Size of the entity-body in bytes
                Content-Location  Canonical URI of the resource requested
                Content-Type  Counterpart to Accept. Data format served
                Date  The time the request was fulfilled (required)
                ETag  Opaque string to a specific version of a representation
                Last-Modified  Counterpart to If-Modified-Since
Message Parameterization
     HTTP Headers
65


        Standard Headers
            Response
                Location  Multiple interpretations, depending on status code
                     201 (“Created”)
                     300 (“Multiple Choices”)
                     301 (“Moved Permanently”)
                     302 (“Found”)
                     303 (“See Other)
                     307 (”Temporary Redirect”)




                         More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14
Message Parameterization
     HTTP Response Codes
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
Message Parameterization
     HTTP Response Codes
67


        The Bare Minimum
          200 (“OK”)
          201 (“Created”)

          301 (“Moved Permanently”)

          400 (“Bad Request”)

          404 (“Not Found”)

          410 (“Gone”)

          409 (“Conflict”)

          500 (“Internal Server Error”)
Message Parameterization
     HTTP Response Codes
68


        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
Agenda
69


        The Programmable Web
        The Resource-Oriented Architecture
        Designing Resource-Oriented Services
        Message Parameterization
        Standardized Service Clients
        Security
        Directory of Frameworks
        References
70   Standardized Service Clients
      Introduction & Use Cases
      Proposed Standard
Standardized Service Clients
     Introduction & Use Cases
71


        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 Cases
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
Standardized Service Clients
     Proposed Standard
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
Standardized Service Clients
       Proposed Standard
74


         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 Standard
75


         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 Standard
76


         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>
Agenda
77


        The Programmable Web
        The Resource-Oriented Architecture
        Designing Resource-Oriented Services
        Message Parameterization
        Standardized Service Clients
        Security
        Directory of Frameworks
        References
78   Security
      Authentication & Authorization
      Standard Authentication Types

      Extended Authentication Types
Security
     Authentication & Authorization
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
Security
     Standard Authentication Types
80


        HTTP Basic Authentication
          Challenge-based approach
          Credential
                Username and password
            Algorithm
                Combined into a single string
                Encoded with Base-64 encoding
                Put in the request header “Authorization”
Security
     Standard Authentication Types
81


        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 Types
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)
Security
     Standard Authentication Types
83


        HTTP Digest Authentication
          Challenge-based approach
          Credential
                Request method and path
                Four pieces of information from the challenge
                Username and password
                Client-side nonce
                Sequence number
            Algorithm
                Combined into a single string
                Encoded with MD5 encoding
                Put in the request header “Authorization”
Security
     Standard Authentication Types
84


        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 Types
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
Security
     Extended Authentication Types
86


        WSSE Username Token
          Ported from SOAP to HTTP
          Based on WS-Security Extension, Username Token

          Based on challenge as well

          Credential
                Password Digest
                Client-side nonce
                Creation date
            Algorithm
                Client generates a nonce
                Then hashed their password along with the nonce and date
                Encodes with Base-64 encoding
Security
     Extended Authentication Types
87


        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 Types
88


        WSSE Username Token
            Positive
                Secure even over unencrypted HTTP
                Password not transferred over the network
            Negative
                The server must store the password as plain text
            Solution
                The complexity of Digest is meat to overcome this limitation
Security
     Extended Authentication Types
89


        New Approaches
          API Key
          OAuth
Agenda
90


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

      Python

      Ruby
Directory of Frameworks
     Java
92


        Restlet
         http://www.restlet.org/


        JBoss REST Easy
         http://www.jboss.org/resteasy/


        Glassfish Jersey
         https://jersey.dev.java.net/
Directory of Frameworks
     Java
93


        SerfJ
         http://serfj.sourceforge.net/


        Play
         http://www.playframework.org/
Directory of Frameworks
     PHP
94


        Zend Framework (Zend_Rest)
         http://framework.zend.com/


        Recess
         http://recessframework.org/


        Tonic
         http://tonic.sourceforge.net/
Directory of Frameworks
     Python
95


        Django
         http://www.djangoproject.com/


        Cherry Py
         http://www.cherrypy.org/
Directory of Frameworks
     Ruby
96


        Rails
         http://www.rubyonrails.org/


        Sinatra
         http://www.sinatrarb.com/
Agenda
97


        The Programmable Web
        The Resource-Oriented Architecture
        Designing Resource-Oriented Services
        Message Parameterization
        Standardized Service Clients
        Security
        Directory of Frameworks
        References
98   References
        Books & Specs
References
     Books & Specs
99




                     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/

More Related Content

What's hot

JavaOne 2009 - TS-5276 - RESTful Protocol Buffers
JavaOne 2009 - TS-5276 - RESTful  Protocol BuffersJavaOne 2009 - TS-5276 - RESTful  Protocol Buffers
JavaOne 2009 - TS-5276 - RESTful Protocol BuffersMatt O'Keefe
 
Wireshark http solution_v6.1
Wireshark http solution_v6.1Wireshark http solution_v6.1
Wireshark http solution_v6.1Yasin Abdullah
 
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...panagenda
 
10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code
10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code
10 Lines or Less; Interesting Things You Can Do In Java With Minimal CodeKathy Brown
 
Jaimin chp-7 - application layer- 2011 batch
Jaimin   chp-7 - application layer- 2011 batchJaimin   chp-7 - application layer- 2011 batch
Jaimin chp-7 - application layer- 2011 batchJaimin Jani
 
Web Application Security 101 - 02 The Basics
Web Application Security 101 - 02 The BasicsWeb Application Security 101 - 02 The Basics
Web Application Security 101 - 02 The BasicsWebsecurify
 
Memento: TimeGates, TimeBundles, and TimeMaps
Memento: TimeGates, TimeBundles, and TimeMapsMemento: TimeGates, TimeBundles, and TimeMaps
Memento: TimeGates, TimeBundles, and TimeMapsMichael Nelson
 
[India Merge World Tour] Meru Networks
[India Merge World Tour] Meru Networks[India Merge World Tour] Meru Networks
[India Merge World Tour] Meru NetworksPerforce
 
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and Rails
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and RailsAnchoring Trust: Rewriting DNS for the Semantic Network with Ruby and Rails
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and RailsEleanor McHugh
 
Juglouvain http revisited
Juglouvain http revisitedJuglouvain http revisited
Juglouvain http revisitedmarctritschler
 
Writing and using php streams and sockets
Writing and using php streams and socketsWriting and using php streams and sockets
Writing and using php streams and socketsElizabeth Smith
 
Micro HTTP Server Implemented in C @ COSCUP 2016
Micro HTTP Server Implemented in C @ COSCUP 2016Micro HTTP Server Implemented in C @ COSCUP 2016
Micro HTTP Server Implemented in C @ COSCUP 2016Jian-Hong Pan
 
DNS, DHCP Configuration
DNS, DHCP Configuration DNS, DHCP Configuration
DNS, DHCP Configuration Anik Saha
 
White Paper: Perforce Administration Optimization, Scalability, Availability ...
White Paper: Perforce Administration Optimization, Scalability, Availability ...White Paper: Perforce Administration Optimization, Scalability, Availability ...
White Paper: Perforce Administration Optimization, Scalability, Availability ...Perforce
 
Win pcap filtering expression syntax
Win pcap  filtering expression syntaxWin pcap  filtering expression syntax
Win pcap filtering expression syntaxVota Ppt
 

What's hot (20)

JavaOne 2009 - TS-5276 - RESTful Protocol Buffers
JavaOne 2009 - TS-5276 - RESTful  Protocol BuffersJavaOne 2009 - TS-5276 - RESTful  Protocol Buffers
JavaOne 2009 - TS-5276 - RESTful Protocol Buffers
 
Wireshark http solution_v6.1
Wireshark http solution_v6.1Wireshark http solution_v6.1
Wireshark http solution_v6.1
 
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...
BP107: Ten Lines Or Less: Interesting Things You Can Do In Java With Minimal ...
 
10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code
10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code
10 Lines or Less; Interesting Things You Can Do In Java With Minimal Code
 
Jaimin chp-7 - application layer- 2011 batch
Jaimin   chp-7 - application layer- 2011 batchJaimin   chp-7 - application layer- 2011 batch
Jaimin chp-7 - application layer- 2011 batch
 
Curl
CurlCurl
Curl
 
Application layer
Application layerApplication layer
Application layer
 
Web Application Security 101 - 02 The Basics
Web Application Security 101 - 02 The BasicsWeb Application Security 101 - 02 The Basics
Web Application Security 101 - 02 The Basics
 
Memento: TimeGates, TimeBundles, and TimeMaps
Memento: TimeGates, TimeBundles, and TimeMapsMemento: TimeGates, TimeBundles, and TimeMaps
Memento: TimeGates, TimeBundles, and TimeMaps
 
[India Merge World Tour] Meru Networks
[India Merge World Tour] Meru Networks[India Merge World Tour] Meru Networks
[India Merge World Tour] Meru Networks
 
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and Rails
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and RailsAnchoring Trust: Rewriting DNS for the Semantic Network with Ruby and Rails
Anchoring Trust: Rewriting DNS for the Semantic Network with Ruby and Rails
 
Juglouvain http revisited
Juglouvain http revisitedJuglouvain http revisited
Juglouvain http revisited
 
Writing and using php streams and sockets
Writing and using php streams and socketsWriting and using php streams and sockets
Writing and using php streams and sockets
 
ZendCon 08 php 5.3
ZendCon 08 php 5.3ZendCon 08 php 5.3
ZendCon 08 php 5.3
 
Python at Facebook
Python at FacebookPython at Facebook
Python at Facebook
 
Micro HTTP Server Implemented in C @ COSCUP 2016
Micro HTTP Server Implemented in C @ COSCUP 2016Micro HTTP Server Implemented in C @ COSCUP 2016
Micro HTTP Server Implemented in C @ COSCUP 2016
 
Netkitmig
NetkitmigNetkitmig
Netkitmig
 
DNS, DHCP Configuration
DNS, DHCP Configuration DNS, DHCP Configuration
DNS, DHCP Configuration
 
White Paper: Perforce Administration Optimization, Scalability, Availability ...
White Paper: Perforce Administration Optimization, Scalability, Availability ...White Paper: Perforce Administration Optimization, Scalability, Availability ...
White Paper: Perforce Administration Optimization, Scalability, Availability ...
 
Win pcap filtering expression syntax
Win pcap  filtering expression syntaxWin pcap  filtering expression syntax
Win pcap filtering expression syntax
 

Viewers also liked

$8000 Fthb Tax Credit
$8000 Fthb Tax Credit$8000 Fthb Tax Credit
$8000 Fthb Tax Creditguest7536ce
 
Package Design Portfolio
Package Design PortfolioPackage Design Portfolio
Package Design PortfolioVerve Creative
 
Agile Process Scalability
Agile Process ScalabilityAgile Process Scalability
Agile Process ScalabilityOtavio Ferreira
 
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...Mike Peditto
 
Semantic Web Services: A RESTful Approach
Semantic Web Services: A RESTful ApproachSemantic Web Services: A RESTful Approach
Semantic Web Services: A RESTful ApproachOtavio Ferreira
 
Development Team Engagement + Development Process
Development Team Engagement + Development ProcessDevelopment Team Engagement + Development Process
Development Team Engagement + Development ProcessOtavio Ferreira
 
Aspect Oriented Software Development
Aspect Oriented Software DevelopmentAspect Oriented Software Development
Aspect Oriented Software DevelopmentOtavio Ferreira
 
Agile Development Metrics
Agile Development MetricsAgile Development Metrics
Agile Development MetricsOtavio Ferreira
 
Wynn Resorts Culture case study
Wynn Resorts Culture case studyWynn Resorts Culture case study
Wynn Resorts Culture case studyMike Peditto
 
Neck Dissections
Neck DissectionsNeck Dissections
Neck Dissectionsguest26910d
 
How to succeed in business as told by Biggie’s “Juicy”
How to succeed in business as told by Biggie’s “Juicy”How to succeed in business as told by Biggie’s “Juicy”
How to succeed in business as told by Biggie’s “Juicy”Mike Peditto
 

Viewers also liked (16)

Incremental Marketing On A Micro Budget
Incremental Marketing On A Micro BudgetIncremental Marketing On A Micro Budget
Incremental Marketing On A Micro Budget
 
$8000 Fthb Tax Credit
$8000 Fthb Tax Credit$8000 Fthb Tax Credit
$8000 Fthb Tax Credit
 
Package Design Portfolio
Package Design PortfolioPackage Design Portfolio
Package Design Portfolio
 
Agile Process Scalability
Agile Process ScalabilityAgile Process Scalability
Agile Process Scalability
 
Ghw website-prod2
Ghw website-prod2Ghw website-prod2
Ghw website-prod2
 
Agile Management Tools
Agile Management ToolsAgile Management Tools
Agile Management Tools
 
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...
Straight Outta Consciousness: Virtues of positive living as told via 
Ice Cub...
 
Semantic Web Services: A RESTful Approach
Semantic Web Services: A RESTful ApproachSemantic Web Services: A RESTful Approach
Semantic Web Services: A RESTful Approach
 
Development Team Engagement + Development Process
Development Team Engagement + Development ProcessDevelopment Team Engagement + Development Process
Development Team Engagement + Development Process
 
Incremental Marketing For Public Relations
Incremental Marketing For Public RelationsIncremental Marketing For Public Relations
Incremental Marketing For Public Relations
 
Agile Modeling
Agile ModelingAgile Modeling
Agile Modeling
 
Aspect Oriented Software Development
Aspect Oriented Software DevelopmentAspect Oriented Software Development
Aspect Oriented Software Development
 
Agile Development Metrics
Agile Development MetricsAgile Development Metrics
Agile Development Metrics
 
Wynn Resorts Culture case study
Wynn Resorts Culture case studyWynn Resorts Culture case study
Wynn Resorts Culture case study
 
Neck Dissections
Neck DissectionsNeck Dissections
Neck Dissections
 
How to succeed in business as told by Biggie’s “Juicy”
How to succeed in business as told by Biggie’s “Juicy”How to succeed in business as told by Biggie’s “Juicy”
How to succeed in business as told by Biggie’s “Juicy”
 

Similar to API Design Workshop

Similar to API Design Workshop (20)

PHP Training: Module 1
PHP Training: Module 1PHP Training: Module 1
PHP Training: Module 1
 
Under the Covers with the Web
Under the Covers with the WebUnder the Covers with the Web
Under the Covers with the Web
 
HTTP & HTML & Web
HTTP & HTML & WebHTTP & HTML & Web
HTTP & HTML & Web
 
HTTP
HTTPHTTP
HTTP
 
Caching on the Edge
Caching on the EdgeCaching on the Edge
Caching on the Edge
 
P4- Consider the following string of ASCII characters that were captur.docx
P4- Consider the following string of ASCII characters that were captur.docxP4- Consider the following string of ASCII characters that were captur.docx
P4- Consider the following string of ASCII characters that were captur.docx
 
HTTP
HTTPHTTP
HTTP
 
IBM dwLive, "Internet & HTTP - 잃어버린 패킷을 찾아서..."
IBM dwLive, "Internet & HTTP - 잃어버린 패킷을 찾아서..."IBM dwLive, "Internet & HTTP - 잃어버린 패킷을 찾아서..."
IBM dwLive, "Internet & HTTP - 잃어버린 패킷을 찾아서..."
 
HTTP/2 Introduction
HTTP/2 IntroductionHTTP/2 Introduction
HTTP/2 Introduction
 
HTTP
HTTPHTTP
HTTP
 
HTTP/2 for Developers
HTTP/2 for DevelopersHTTP/2 for Developers
HTTP/2 for Developers
 
Hypertex transfer protocol
Hypertex transfer protocolHypertex transfer protocol
Hypertex transfer protocol
 
Starting With Php
Starting With PhpStarting With Php
Starting With Php
 
Spider Course Day 1
Spider Course Day 1Spider Course Day 1
Spider Course Day 1
 
Web technologies: HTTP
Web technologies: HTTPWeb technologies: HTTP
Web technologies: HTTP
 
Application layer
Application layerApplication layer
Application layer
 
Introducing HTTP/2
Introducing HTTP/2Introducing HTTP/2
Introducing HTTP/2
 
HTTP1.1/2 overview
HTTP1.1/2 overviewHTTP1.1/2 overview
HTTP1.1/2 overview
 
WWW and HTTP
WWW and HTTPWWW and HTTP
WWW and HTTP
 
Http/2
Http/2Http/2
Http/2
 

Recently uploaded

UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7DianaGray10
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?IES VE
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureEric D. Schabell
 
9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding TeamAdam Moalla
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6DianaGray10
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Adtran
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-pyJamie (Taka) Wang
 
Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Commit University
 
Nanopower In Semiconductor Industry.pdf
Nanopower  In Semiconductor Industry.pdfNanopower  In Semiconductor Industry.pdf
Nanopower In Semiconductor Industry.pdfPedro Manuel
 
Computer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsComputer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsSeth Reyes
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfinfogdgmi
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfDaniel Santiago Silva Capera
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesMd Hossain Ali
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfAijun Zhang
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IES VE
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsSafe Software
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesDavid Newbury
 

Recently uploaded (20)

UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability Adventure
 
9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-py
 
Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)
 
Nanopower In Semiconductor Industry.pdf
Nanopower  In Semiconductor Industry.pdfNanopower  In Semiconductor Industry.pdf
Nanopower In Semiconductor Industry.pdf
 
Computer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsComputer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and Hazards
 
201610817 - edge part1
201610817 - edge part1201610817 - edge part1
201610817 - edge part1
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdf
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdf
 
20150722 - AGV
20150722 - AGV20150722 - AGV
20150722 - AGV
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
 
20230104 - machine vision
20230104 - machine vision20230104 - machine vision
20230104 - machine vision
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond Ontologies
 

API Design Workshop

  • 1. API DESIGN August 2010 Otavio Ferreira (@otaviofff)
  • 2. Agenda 2  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 Envelopes 4  HTTP  Hypertext Transfer Protocol  Application layer, document-based, request-response protocol for distributed, collaborative, hypermedia information systems  Foundation of the Web  Strict envelop structure
  • 5. The Programmable Web HTTP: Documents in Envelopes 5  HTTP Request (1/4) GET /index.html HTTP/1.1 Host: www.oreilly.com User-Agent: Mozilla/5.0 Accept: text/xml, text/html, application/xml, ... Accept-Language: us, en Accept-Encoding: gzip, deflate Accept-Charset: ISO-8859, UTF-8 Keep-Alive: 300 Connection: Keep-Alive
  • 6. The Programmable Web HTTP: Documents in Envelopes 6  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 Envelopes 7  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 Envelopes 8  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 Envelopes 9  HTTP Response (1/4) HTTP/1.1 200 OK Date: Mon 26 Jul 2010 15:35:55 GMT Server: Apache Last-Modified: Fri 23 Jul 2010 14:01:13 GMT Accept-Ranges: bytes Content-Length: 43302 Content-Type: text/html X-Cache: MISS from www.oreilly.com Keep-Alive: timeout=15, max=1000 Connection: Keep-Alive <!DOCTYPE html PUBLIC “...”> <html>...</html>
  • 10. The Programmable Web HTTP: Documents in Envelopes 10  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 Envelopes 11  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 Envelopes 12  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 Information 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
  • 14. The Programmable Web Method Information 14  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 Information 15 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 Information 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
  • 17. The Programmable Web Scoping Information 17  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 Information 18 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 Architectures 19  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 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
  • 21. The Programmable Web Technologies 21  Classification  Technologies do not classify services  Architectural styles do  Technologies  HTTP  URI  XML-RPC  SOAP  WS-*  WSDL, WADL  XML, JSON, XHTML, RDF, ...
  • 22. Agenda 22  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 Introduction 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
  • 25. The Resource-Oriented Architecture Introduction 25  Concepts  Resource  Representation  Uniform Identifier  Uniform Interface  Principles  Addressability  Connectedness  Statelessness
  • 26. The Resource-Oriented Architecture Concepts 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
  • 27. The Resource-Oriented Architecture Concepts 27  Identifying Resources  If another party [users] might reasonably want to...  Create a hypertext link to it  Make or refute assertions about it  Retrieve or cache a representation of it  Include all or part of it by reference into another representation  Annotate it  Perform other operations on it  Then, it has to be a resource – Architecture of the World Wide Web, Volume One, 2004, W3C
  • 28. The Resource-Oriented Architecture Concepts 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) { "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 Concepts 29  Deciding between Representations  Multiple URIs  HTTP header ”Accept”  HTTP header “Accept-Language”  Other HTTP request metadata
  • 30. The Resource-Oriented Architecture Concepts 30  Uniform Identifier  URI – Uniform Resource Identifier  It is the name and address of a resource  Each resource has to have at least one URI  Uniform Identifier Examples  http://example.com/map/bra/ce/fortaleza  http://example.com/wiki/dog  http://example.com/search/dog  http://example.com/software/release/1.0.3.tar.gz  http://example.com/discography/coldplay  http://example.com/user/alice/humor
  • 31. The Resource-Oriented Architecture Concepts 31  Analyzing Uniform Identifiers  URIs should be descriptive  URIs should have clear, intuitive structure and notation  URIs should vary in predictable ways  Clients may create their own entry points into services  Constraints  Every URI designates one Resource  Every Resource might be designated by various URIs  Defining a canonical URI is a best practice  Response code 303 (“See Also”)  Response header “Content-Location”
  • 32. The Resource-Oriented Architecture Concepts 32  Uniform Interface  Unified set of common operations  Valid for all services, regardless of their resources  Operations & HTTP Methods  Retrieve a representation of a resource: GET  Delete an existing resource: DELETE  Create a new resource:  PUT to a new URI  POST to an existing, factory URI  Modify an existing resource: PUT to an existing URI
  • 33. The Resource-Oriented Architecture Concepts 33  Secondary Operations & HTTP Methods  Retrieve a metadata-only representation: HEAD  Check which methods a resource supports: OPTIONS  Derived Properties  Safety (GET, HEAD)  Idempotence (GET, HEAD, PUT, DELETE)
  • 34. The Resource-Oriented Architecture Principles 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 /resource/1 /resource /resource/2
  • 35. The Resource-Oriented Architecture Principles 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 /resource/1 /resource /resource/2
  • 36. The Resource-Oriented Architecture Principles 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
  • 37. The Resource-Oriented Architecture Principles 37  Kinds of State  Resource State  Info about the resource  Lives on the server  Application State  Info about the path the client has taken through the application  Lives on the client  Therefore...  A service is stateless if no application state is stored by the server
  • 38. The Resource-Oriented Architecture Principles 38  Statelessness & Scalability  No session replication  No session affinity  Data replication only when the resource state needs to be split across multiple machines  Horizontally scalable services  Statelessness & Caching  One cached item per request (URI)  No dependencies on previous requests
  • 39. The Resource-Oriented Architecture Principles 39 Stateless Search Engine Stateful Search Engine Search Form Initial State “Mice” “Jellyfish” “Mice” “Jellyfish” Initial State Search Form Request Response Connection
  • 40. Agenda 40  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 Design 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
  • 43. Designing RO Services Resource Design 43 Object-Oriented Design Resource-Oriented Design Subscription subscribes to Reader Column Reader Column
  • 44. Designing RO Services Turning Requirements into Resources 44  Procedure 1. Figure out the data set 2. Split the data set into resources 3. Name the resources with URIs 4. Expose a subset of the Uniform Interface 5. Design the representations 6. Integrate resources by linking to each other 7. Consider the typical course of events 8. Consider error conditions  Lets try an example...
  • 45. Designing RO Services Turning Requirements into Resources 45  Step 1: Figure out the data set: Domain Overview  Free online classifieds website  Ads are regional  Ads are bound to products  Products belong to categories  Any registered user can comment on ads  Advertisers can publish any number of ads  Shoppers can place orders from within the site  Orders may refer to more than one ad  …
  • 46. Designing RO Services Turning Requirements into Resources 46  Step 1: Figure out the data set: Domain Model
  • 47. Designing RO Services Turning Requirements into Resources 47  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 Resources 48  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 Resources 49  Step 4: Expose a subset of the Uniform Interface Resource GET HEAD POST PUT DELETE /ad/{id} /order/{id} /profile/{id} /product/{id} /category/{id} /ad/{id}/comment/{seq} /ad
  • 50. Designing RO Services Turning Requirements into Resources 50  Step 5: Design the representations: /ad/{id} <html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en”> <head><title>Oakley Jupiter Black </title></head> <body> <dl class=“ad”> <dt>id</dt> <dd>970</dd> <dt>created</dt> <dd>2010-01-17T14:34:01-03:00</dd> <dt>description</dt> <dd>…</dd> <dt>price</dt> <dd>390.00</dd> <dt>location</dt> <dd>Salvador, BA, BRA</dd> <dt>advertiser</dt> <dd><a class=“profile” href=“/profile/bgrenn“>Ben Green</a></dd> <dt>product</dt> <dd><a class=“product” href=“/product/621“>Oakley Jupiter</a>/dd> <dt>comments</dt> <dd> <ol class=“comments”> <li><a class=“comment” href=“/ad/970/comment/1”>Great</a></li> <li><a class=“comment” href=“/ad/970/comment/2”>Average</a></li> </ol></dd> </dl> </body></html>
  • 51. Designing RO Services Turning Requirements into Resources 51  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 Resources 52  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 Resources 53  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 Resources 54  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 Resources 55  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 Resources 56  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 Resources 57  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 Resources 58  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 Resources 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
  • 60. Agenda 60  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 Headers 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”)
  • 63. Message Parameterization HTTP Headers 63  Standard Headers  Request  Accept  Data format to be used on representations served  Accept-Charset  Character set to be used on representations  Accept-Encoding  Algorithm to compress representations  Accept-Language  Human language in the representations  Authorization  Encoded authorization credential  Date  The time the request was sent  Host  Domain name part of URI (required)  If-Modified-Since  Backbone of conditional GET  User-Agent  Kind of software making the request
  • 64. Message Parameterization HTTP Headers 64  Standard Headers  Response  Content-Encoding  Counterpart to Accept-Encoding  Content-Language  Counterpart to Accept-Language  Content-Length  Size of the entity-body in bytes  Content-Location  Canonical URI of the resource requested  Content-Type  Counterpart to Accept. Data format served  Date  The time the request was fulfilled (required)  ETag  Opaque string to a specific version of a representation  Last-Modified  Counterpart to If-Modified-Since
  • 65. Message Parameterization HTTP Headers 65  Standard Headers  Response  Location  Multiple interpretations, depending on status code  201 (“Created”)  300 (“Multiple Choices”)  301 (“Moved Permanently”)  302 (“Found”)  303 (“See Other)  307 (”Temporary Redirect”) More: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14
  • 66. Message Parameterization HTTP Response Codes 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
  • 67. Message Parameterization HTTP Response Codes 67  The Bare Minimum  200 (“OK”)  201 (“Created”)  301 (“Moved Permanently”)  400 (“Bad Request”)  404 (“Not Found”)  410 (“Gone”)  409 (“Conflict”)  500 (“Internal Server Error”)
  • 68. Message Parameterization HTTP Response Codes 68  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. Agenda 69  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 Cases 71  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 Cases 72  Use Cases  Application modeling and visualization  Support for the development of resource modeling tools  Resource relationship analysis and manipulation  Code generation  Automated generation of stub and skeleton code  Code for the manipulation of resource representations  Configuration  Portable format for the configuration of both client and server  Client standardization  General-purpose wrapper for any RESTful service
  • 73. Standardized Service Clients Proposed Standard 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
  • 74. Standardized Service Clients Proposed Standard 74  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 Standard 75  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 Standard 76  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. Agenda 77  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 & Authorization 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
  • 80. Security Standard Authentication Types 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”
  • 81. Security Standard Authentication Types 81  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 Types 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)
  • 83. Security Standard Authentication Types 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”
  • 84. Security Standard Authentication Types 84  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 Types 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
  • 86. Security Extended Authentication Types 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
  • 87. Security Extended Authentication Types 87  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 Types 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
  • 89. Security Extended Authentication Types 89  New Approaches  API Key  OAuth
  • 90. Agenda 90  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 Java 92  Restlet http://www.restlet.org/  JBoss REST Easy http://www.jboss.org/resteasy/  Glassfish Jersey https://jersey.dev.java.net/
  • 93. Directory of Frameworks Java 93  SerfJ http://serfj.sourceforge.net/  Play http://www.playframework.org/
  • 94. Directory of Frameworks PHP 94  Zend Framework (Zend_Rest) http://framework.zend.com/  Recess http://recessframework.org/  Tonic http://tonic.sourceforge.net/
  • 95. Directory of Frameworks Python 95  Django http://www.djangoproject.com/  Cherry Py http://www.cherrypy.org/
  • 96. Directory of Frameworks Ruby 96  Rails http://www.rubyonrails.org/  Sinatra http://www.sinatrarb.com/
  • 97. Agenda 97  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 & Specs 99 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. 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/