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 E. Collection+JSON Media Type

Collection+JSON is a JSON-based read/write hypermedia type designed to support the management and querying of simple collections. It is similar to the The Atom Syndication Format (RFC 4287) and The Atom Publishing Protocol (RFC 5023) . However, Collection+JSON defines both the format and the semantics in a single document and includes support for Query Templates and expanded write support through the use of a Write Template.

The IANA Registry lists the media type identifier as application/vnd.Collection+JSON.

General Concepts

This section contains general concepts that apply to all Collection+JSON documents.

The Collection+JSON hypermedia type is designed to support full read/write capability for simple lists (e.g. contacts, tasks, blog entries, etc.). The standard application semantics supported by this media type include Create, Read, Update, and Delete (CRUD) along with support for predefined queries including query templates (similar to HTML GET forms). Write operations are defined using a template object supplied by the server as part of the response representation.

Each item in a Collection+JSON collection has an assigned URI (via the href property) and an optional array of one or more data elements along with an optional array of one or more link elements. ...