Server side Abstractions for Hypermedia APIs

---

Convener: Michael Tiller (@mtiller)

Experience with Hypermedia: Built multiple hypermedia APIs using HAL as a representation format and a hypermedia client built using Traverson

---

Gist

Michael has written a couple of hypermedia APIs and was frustrated with amount of boilerplate code that was required to implement them and lack of code reusability for some common cross-cutting concerns. He started working on a framework that will provide higher-level servers-side abstractions allowing him to focus on defining resources, relations between them, applicable actions and state transitions.

Michael is in the process of designing v2 of his framework incorporating some valuable lessons learned from v1. He shared some high-level concepts in v2 and was interested in feedback and validation of some of his ideas.

Details

Language

Framework is implemented in Go.

Core Concepts

Registry

• Entry point for an entire API
• Exposed as a resource
• First-class citizen of the DSL in Go

Relations

• Relations are registered in Registry
• Built-in IANA relations
• URI that points to a description of a domain-specific relation

Context

• Defines URI templates and rules for building them

Resource

• Has a name
• Define mapping between context and representation
• Defines parameters required for building queries (filtering, sorting, pagination)

Representations

• Description
• Relations
• Parameters
• May contain redirect logic

Actions

• Resource-specific
• Describes action: idempotent/non-idempotent, safe/unsafe, etc.

Representations

• Description
• Relations
• Parameters
• May contain redirect logic

Transformations

• Handle content negotiation
• Maps media type to an appropriate representation

Environment

• Middleware for cross-cutting concerns (authentication, authorization, caching)
• Defines policies that will be executed before accessing a resource

Accessor (?)

• Defines policies that will be executed before accessing a resource