O'Reilly logo

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Building Hypermedia APIs with HTML5 and Node

Building Hypermedia APIs with HTML5 and Node

6 reviews
by Mike Amundsen
Publisher: O'Reilly Media, Inc.
Release Date: November 2011
ISBN: 9781449309497
View table of contents
Start reading

Book Description

With this concise book, you’ll learn the art of building hypermedia APIs that don’t simply run on the Web, but that actually exist in the Web. You’ll start with the general principles and technologies behind this architectural approach, and then dive hands-on into three fully-functional API examples.

Too many APIs rely on concepts rooted in desktop and local area network patterns that don’t scale well—costly solutions that are difficult to maintain over time. This book shows system architects and web developers how to design and implement human- and machine-readable web services that remain stable and flexible as they scale.

  • Learn the H-Factors for representing application metadata across all media types and formats
  • Understand the four basic design elements for authoring hypermedia types
  • Convert a simple read-only XML-based media type into a successful API design
  • Examine the challenges and advantages of designing a hypermedia type with JSON
  • Use HTML5’s rich set of hypermedia controls in the API design process
  • Learn the details of documenting, publishing, and registering media type designs and link-relation types

Table of Contents

  1. Foreword
  2. Dedication
  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. Copyright