Hypermedia design to navigate a hierarchy

[snow6oy]

Hola,

Once you take out the domain stuff, the API that I am designing is based on a hierarchical data model. The links needed to navigate the model could be as simple as:

• root node [item]
  
• parent [item]
  
• sibling nodes [collection]

The client/server context is browser based. After consulting (the excellent) Building Hypermedia APIs with HTML5 and Node my initial design uses the following tags to describe the links: id, name, class and rel.

Given that tree structures are so common place, I looked for an existing Hypermedia design but found only academic references.

Are there any implementations that I might refer to. Or perhaps some ideas on how to approach the design?

Thanks

Gavin

[Steve Klabnik]

You'd probably like HAL, Collection+JSON, or JSON API.

HAL fits this very directly, with embedded resource support. If you
don't want to embed, you can just link.

C+J is designed around collections, which seems like the main focus of your app.

JSON API is also focused around collections, but exclusively includes
links to children rather having an option to embed them.

[Kevin Swiber]

While there are a few existing hypermedia formats you can use, there aren't many real-world, in-use, public implementations to browse.  It sounds like you're just looking for Web Linking features.

Netflix: http://developer.netflix.com/docs

GitHub: http://developer.github.com/v3

Netflix uses RFC5988-compatible Web linking.  GitHub just includes URL properties.

The link relation on this is somewhat significant.  Potential rel values in your use case might be: next, prev, up, index, contents, first, last, item.  The full list is available here: http://www.iana.org/assignments/link-relations/link-relations.xml

Are you planning to include an id, name, class, and rel for each link?  I'd be curious how you're using these fields.  Some common fields found on links are rel, href, title, and/or type.

Cheers,

-- 

Kevin Swiber

@kevinswiber

https://github.com/kevinswiber

[snow6oy .]

Steve, Kevin

Thanks for your replies. After some reading of the material you recommended I came up with the following. It's a bit out of context,but hopefully makes some sense ..

The link-relations from IANA was particularly useful.

GET /resources/1

[{

  "id": 1,

  "name": "resource",

  "class": "list",                // can be list, item or tree

  "depth": 0,                     // depth of hierarchy in response data, 0 = list

  "links": {

    "class": "resource domain",   // domain changes when we descend into the data model

    "rel": [

      "sibling 1",

      "sibling 2",

      "sibling 3"

    ],

    "next": {

      "rel": "next resource",     // descend into tree

      "href": "..."

    },

    "prev": {

      "rel": "prev resource",     // ascend

      "href": null

    }

  },

  "filters": [],                  // availability varies according to domain

  "faults": []                    

}]

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/WrXSwdIEe-U/unsubscribe?hl=en.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
http://twitter.com/snow6oy