book

Building Hypermedia APIs with HTML5 and Node

by Mike Amundsen

November 2011

Intermediate to advanced

240 pages

5h 38m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Hypermedia API DesignIntended AudienceWhat Is Not CoveredContents of This BookCoding Style for This BookConventions Used in This BookUsing Code ExamplesSafari® Books OnlineHow to Contact UsAcknowledgements
HTTP, MIME, and HypermediaHTTP Is the Transfer ProtocolMIME Is the Media Type StandardHypermedia Is the EngineFrom links to controlsHypermedia typesProgramming the Web with Hypermedia APIsThe Type-Marshaling DilemmaShared schemaURI constructionPayload decorationNarrow media typesThe Hypermedia SolutionMetadata about the dataMetadata about the applicationSummaryIdentifying Hypermedia : H-FactorsLink FactorsEmbedding Links (LE)Outbound Links (LO)Templated Links (LT)Idempotent Links (LI)Non-Idempotent Links (LN)Control FactorsRead Controls (CR)Update Controls (CU)Method Controls (CM)Link Annotation Controls (CL)SummaryHypermedia Design ElementsBase FormatXMLJSONHTMLOthersState TransferRead-onlyPredefinedAd-HocDomain StyleSpecificGeneralAgnosticApplication FlowNoneIntrinsicAppliedSummaryWhat’s Next?
ScenarioDesigning the Maze XML Media TypeIdentifying the State TransitionsSelecting the Basic Design ElementsThe Maze+XML DocumentThe collection elementThe item elementThe cell elementThe error elementSample DataThe Server CodeThe Collection State ResponseThe Item State ResponseThe Cell State ResponseThe Exit State ResponseThe Client CodeMaze Game ExampleHTML5 MarkupJavaScriptMaze Bot ExampleHTML5 MarkupJavaScriptSummary
ScenarioDesigning the Collection+JSON Media-TypeIdentifying the State TransitionsSelecting the Basic Design ElementsThe Collection+JSON DocumentObjectsThe collection objectThe error objectThe template objectArraysThe data arrayThe items arrayThe links arrayThe queries arrayThe Tasks Application SemanticsThe Data ModelThe Write TemplatePredefined QueriesSample DataTask DocumentsDesign DocumentThe Server CodeThe Collection ResponseThe Item ResponseThe Query RepresentationsHandling Template WritesThe Client CodeThe Tasks SPI ExampleHTML5 markupJavaScriptThe Tasks Command Line ExampleThe general approachThe add-task.js applicationSummary
ScenarioDesigning the Microblog Media TypeExpressing Application Domain Semantics in HTML5Identifying the State TransitionsState blocksUsersMessagesQueriesTransfer blocksCreate new userUpdate existing userFollow a userSearch for usersAdd a new messageReply to an existing messageSearch for messagesSelecting the Basic Design ElementsThe Microblog Application ProfileCurrent user and state dataID attribute valuesClass attribute valuesName attributes valuesRel attribute valuesSample DataUser DocumentsMessage DocumentsFollow DocumentsDesign DocumentThe Server CodeAuthenticating UsersRegistering a New UserMessage ResponsesUser ResponsesThe Client CodeThe POSH ExampleThe Ajax QuoteBot ExampleThe QuoteBot scenarioQuoteBot HTML5QuoteBot JavaScriptSetup codeMaking requestsProcessing responsesSupport routinesSummary
Requirements, Compliance, and RFC 2119The RFC 2119 KeywordsSample Documentation Using RFC 2119 KeywordsDefining ComplianceDocumenting Media Type DesignsGeneral LayoutFront matterFormatExamplesTutorialsDocumenting XML DesignsDocumenting JSON DesignsDocumenting HTML DesignsDocumenting Application Domain SpecificsData elementsDomain-specific data elementsDomain-generic data elementsHypermedia affordancesDomain-specific hypermedia controlsDomain-generic hypermedia controlsPublishing Media Type DesignsExtending and Versioning Media TypesExtendingForward compatibilityBackward compatibilityRules for extending media typesExisting design elements cannot be removedThe meaning or processing of existing elements cannot be changedNew design elements must be treated as optionalVersioningDeciding when to version a media typeRules for versioning a media typeIt should be easy to identify new versions of a media typeImplementations should reject unsupported versionsRegistering Media Types and Link RelationsMedia TypesVendor/Personal tree media type registrationsStandard tree media type registrationsLink Relation TypesRegistering link relations with the Microformats communityRegistering link relations with the IANADesign and Implementation TipsJoshua Bloch’s Characteristics of a Good APIRoy Fielding’s Hypertext API GuidelinesJon Postel’s Robustness PrincipleOther ConsiderationsGetting it right but not completeMaintain media type design and schema separatelyAuthentication is not part of the hypermedia designTesting media type designs
Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5

BooksOther
ElementscellcodecollectiondebugerroritemlinkmazemessagetitleAttributesdebughrefrelsidetotalversionLink RelationscollectioncurrenteastexitmazenorthsouthstartwestData TypesCDATANUMBERTEXTURIExtensibility
General ConceptsReading and Writing DataReading collectionsAdding an itemReading an itemUpdating an itemDeleting an itemQuery TemplatesObjectscollectionerrortemplateArraysdataitemslinksqueriesPropertiescodehrefmessagenamepromptrelrendertitlevalueversionLink RelationscollectionitemstemplatequeriesOther Link Relation ValuesData TypesARRAYNUMBEROBJECTSTRINGURIVALUEExtensibility
General ConceptsComplianceDesign CharacteristicsAdditional ConstraintsSemantic ProfileClass Attribute ValuesID Attribute ValuesName Attribute ValuesRel Attribute Values
Source CodePrerequisitesCouchDBNode.jsCloud ServicesAuthoring

Content preview from Building Hypermedia APIs with HTML5 and Node

Chapter 3. JSON Hypermedia

I have the world’s largest collection of seashells. I keep it on all the beaches of the world; perhaps you’ve seen it.

- Stephen Wright

The second example chapter explores the challenges and advantages of using JSON as a base for designing a hypermedia type. The scenario includes requirements for basic read/write semantics for managing simple lists (friends, tasks, blog entries, etc.). This scenario relies on generic design that supports the ability to create customized implementations that reflect specific application domains not considered during the initial design. After designing the type and documenting the application domain, a sample server is built using test data and two clients are to be implemented: one that employs a single-page interface (SPI) model for HTML browsers and one that offers a quick command-line interface built using only Node.js.

Scenario

Unlike the Maze+XML media type, which was designed to support a very specific scenario, this example needs to support a range of similar implementations, that of managing lists such as contacts, tasks, bookmarks, blog entries, comments, etc. Also, unlike the last example, this one requires support for full read/write access to the data. The hypermedia design should contain enough application control information to allow clients to know how (and when) to add, edit, and delete data from the list. Finally, users should be able to discover and execute predefined queries to filter the server responses. ...