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

Appendix D. Maze+XML Media Type

The Maze+XML media type is an XML data format for sharing maze state information between clients and servers. It can be used to implement simple mazes, adventure games, and other related data.

The IANA Registry lists the media type identifier as application/vnd.amundsen.maze+xml.

Elements

Below is a map of the Maze+XML media type. This map shows all of the possible elements, attributes, link relations, and data types.

It should be noted that the media type map below does not necessarily represent a valid instance of a Maze+XML document. It is only useful as a map to explore the various features of the media type:

<maze version="1.0">
  <collection href="URI">
    <link href="URI" rel="maze" />
    <link href="URI" rel="maze" />
    ...
  </collection>
  <item href="URI" >
    <link href="URI" rel="start" />
    <debug>CDATA</debug>
  </item>  
  <cell href="URI"  debug="TEXT" total="NUMBER" side="NUMBER">
    <link href="URI" rel="current" debug="TEXT" total="NUMBER" side="NUMBER" /> <!-- alternate 'current' link -->
    <link href="URI" rel="north" />
    <link href="URI" rel="south" />
    <link href="URI" rel="east" />
    <link href="URI" rel="west" />
    <link href="URI" rel="exit" />
  </cell>
  <error href="URI">
    <title>TEXT</title>
    <code>TEXT</code>
    <message>CDATA</message>
  </error>
</maze>