You are previewing Building Hypermedia APIs with HTML5 and Node.
O'Reilly logo
Building Hypermedia APIs with HTML5 and Node

Book Description

Building Hypermedia APIs with HTML5 and Node shows how to build stable, flexible Web APIs using JavaScript on both client and server. It’s practical examples demonstrate best practices for writing and maintaining Web APIs and provide clear coverage of general principles of hypermedia that appeal to Web architects.

Table of Contents

  1. Building Hypermedia APIs with HTML5 and Node
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. Foreword
    3. Preface
      1. Hypermedia API Design
      2. Intended Audience
      3. What Is Not Covered
      4. Contents of This Book
      5. Coding Style for This Book
      6. Conventions Used in This Book
      7. Using Code Examples
      8. Safari® Books Online
      9. How to Contact Us
      10. Acknowledgements
    4. 1. Understanding Hypermedia
      1. HTTP, MIME, and Hypermedia
        1. HTTP Is the Transfer Protocol
        2. MIME Is the Media Type Standard
        3. Hypermedia Is the Engine
          1. From links to controls
          2. Hypermedia types
      2. Programming the Web with Hypermedia APIs
        1. The Type-Marshaling Dilemma
          1. Shared schema
          2. URI construction
          3. Payload decoration
          4. Narrow media types
        2. The Hypermedia Solution
          1. Metadata about the data
          2. Metadata about the application
          3. Summary
      3. Identifying Hypermedia : H-Factors
        1. Link Factors
          1. Embedding Links (LE)
          2. Outbound Links (LO)
          3. Templated Links (LT)
          4. Idempotent Links (LI)
          5. Non-Idempotent Links (LN)
        2. Control Factors
          1. Read Controls (CR)
          2. Update Controls (CU)
          3. Method Controls (CM)
          4. Link Annotation Controls (CL)
          5. Summary
      4. Hypermedia Design Elements
        1. Base Format
          1. XML
          2. JSON
          3. HTML
          4. Others
        2. State Transfer
          1. Read-only
          2. Predefined
          3. Ad-Hoc
        3. Domain Style
          1. Specific
          2. General
          3. Agnostic
        4. Application Flow
          1. None
          2. Intrinsic
          3. Applied
      5. Summary
      6. What’s Next?
    5. 2. XML Hypermedia
      1. Scenario
      2. Designing the Maze XML Media Type
        1. Identifying the State Transitions
        2. Selecting the Basic Design Elements
        3. The Maze+XML Document
          1. The collection element
          2. The item element
          3. The cell element
          4. The error element
      3. Sample Data
      4. The Server Code
        1. The Collection State Response
        2. The Item State Response
        3. The Cell State Response
        4. The Exit State Response
      5. The Client Code
        1. Maze Game Example
          1. HTML5 Markup
          2. JavaScript
        2. Maze Bot Example
          1. HTML5 Markup
          2. JavaScript
      6. Summary
    6. 3. JSON Hypermedia
      1. Scenario
      2. Designing the Collection+JSON Media-Type
        1. Identifying the State Transitions
        2. Selecting the Basic Design Elements
        3. The Collection+JSON Document
          1. Objects
            1. The collection object
            2. The error object
            3. The template object
          2. Arrays
            1. The data array
            2. The items array
            3. The links array
            4. The queries array
      3. The Tasks Application Semantics
        1. The Data Model
        2. The Write Template
        3. Predefined Queries
      4. Sample Data
        1. Task Documents
        2. Design Document
      5. The Server Code
        1. The Collection Response
        2. The Item Response
        3. The Query Representations
        4. Handling Template Writes
      6. The Client Code
        1. The Tasks SPI Example
          1. HTML5 markup
          2. JavaScript
        2. The Tasks Command Line Example
          1. The general approach
          2. The add-task.js application
      7. Summary
    7. 4. HTML5 Hypermedia
      1. Scenario
      2. Designing the Microblog Media Type
        1. Expressing Application Domain Semantics in HTML5
        2. Identifying the State Transitions
          1. State blocks
            1. Users
            2. Messages
            3. Queries
          2. Transfer blocks
            1. Create new user
            2. Update existing user
            3. Follow a user
            4. Search for users
            5. Add a new message
            6. Reply to an existing message
            7. Search for messages
        3. Selecting the Basic Design Elements
        4. The Microblog Application Profile
          1. Current user and state data
          2. ID attribute values
          3. Class attribute values
          4. Name attributes values
          5. Rel attribute values
      3. Sample Data
        1. User Documents
        2. Message Documents
        3. Follow Documents
        4. Design Document
      4. The Server Code
        1. Authenticating Users
        2. Registering a New User
        3. Message Responses
        4. User Responses
      5. The Client Code
        1. The POSH Example
        2. The Ajax QuoteBot Example
          1. The QuoteBot scenario
          2. QuoteBot HTML5
          3. QuoteBot JavaScript
            1. Setup code
            2. Making requests
            3. Processing responses
            4. Support routines
      6. Summary
    8. 5. Documenting Hypermedia
      1. Requirements, Compliance, and RFC 2119
        1. The RFC 2119 Keywords
        2. Sample Documentation Using RFC 2119 Keywords
        3. Defining Compliance
      2. Documenting Media Type Designs
        1. General Layout
          1. Front matter
          2. Format
          3. Examples
          4. Tutorials
        2. Documenting XML Designs
        3. Documenting JSON Designs
        4. Documenting HTML Designs
        5. Documenting Application Domain Specifics
          1. Data elements
            1. Domain-specific data elements
            2. Domain-generic data elements
          2. Hypermedia affordances
            1. Domain-specific hypermedia controls
            2. Domain-generic hypermedia controls
        6. Publishing Media Type Designs
      3. Extending and Versioning Media Types
        1. Extending
          1. Forward compatibility
          2. Backward compatibility
          3. Rules for extending media types
            1. Existing design elements cannot be removed
            2. The meaning or processing of existing elements cannot be changed
            3. New design elements must be treated as optional
        2. Versioning
          1. Deciding when to version a media type
          2. Rules for versioning a media type
            1. It should be easy to identify new versions of a media type
            2. Implementations should reject unsupported versions
      4. Registering Media Types and Link Relations
        1. Media Types
          1. Vendor/Personal tree media type registrations
          2. Standard tree media type registrations
        2. Link Relation Types
          1. Registering link relations with the Microformats community
          2. Registering link relations with the IANA
      5. Design and Implementation Tips
        1. Joshua Bloch’s Characteristics of a Good API
        2. Roy Fielding’s Hypertext API Guidelines
        3. Jon Postel’s Robustness Principle
        4. Other Considerations
          1. Getting it right but not complete
          2. Maintain media type design and schema separately
          3. Authentication is not part of the hypermedia design
          4. Testing media type designs
    9. A. Afterword
    10. B. References
      1. Chapter 1
      2. Chapter 2
      3. Chapter 3
      4. Chapter 4
      5. Chapter 5
    11. C. Additional Reading
      1. Books
      2. Other
    12. D. Maze+XML Media Type
      1. Elements
        1. cell
        2. code
        3. collection
        4. debug
        5. error
        6. item
        7. link
        8. maze
        9. message
        10. title
      2. Attributes
        1. debug
        2. href
        3. rel
        4. side
        5. total
        6. version
      3. Link Relations
        1. collection
        2. current
        3. east
        4. exit
        5. maze
        6. north
        7. south
        8. start
        9. west
      4. Data Types
        1. CDATA
        2. NUMBER
        3. TEXT
        4. URI
      5. Extensibility
    13. E. Collection+JSON Media Type
      1. General Concepts
        1. Reading and Writing Data
          1. Reading collections
          2. Adding an item
          3. Reading an item
          4. Updating an item
          5. Deleting an item
        2. Query Templates
      2. Objects
        1. collection
        2. error
        3. template
      3. Arrays
        1. data
        2. items
        3. links
        4. queries
      4. Properties
        1. code
        2. href
        3. message
        4. name
        5. prompt
        6. rel
        7. render
        8. title
        9. value
        10. version
      5. Link Relations
        1. collection
        2. items
        3. template
        4. queries
        5. Other Link Relation Values
      6. Data Types
        1. ARRAY
        2. NUMBER
        3. OBJECT
        4. STRING
        5. URI
        6. VALUE
      7. Extensibility
    14. F. Microblogging HTML Semantic Profile
      1. General Concepts
        1. Compliance
        2. Design Characteristics
        3. Additional Constraints
      2. Semantic Profile
        1. Class Attribute Values
        2. ID Attribute Values
        3. Name Attribute Values
        4. Rel Attribute Values
    15. G. IANA Media Type Registration Document
    16. H. IETF Link Relations Internet Draft
    17. I. Source Code, Software, and Installation Notes
      1. Source Code
      2. Prerequisites
      3. CouchDB
      4. Node.js
      5. Cloud Services
      6. Authoring
    18. About the Author
    19. SPECIAL OFFER: Upgrade this ebook with O’Reilly