getting

README

Getting - A hypermedia client for golang

Introduction

The Getting library is an attempt at creating a 'generic' hypermedia client, it supports an opinionated set of modern features REST services might have.

It is a port of the amazing Ketting library for javascript.

The library supports HAL, JSON:API, Web Linking (HTTP Link Header) and HTML5 links.

Example

Coming soon.

Docs

Coming soon.

Notable Features

Getting provides a RESTful interface and make it easier to follow REST best practices more strictly.

It provides some useful abstractions that make it easier to work with true hypermedia / HATEAOS servers. It currently parses HAL and has a deep understanding of links and embedded resources. There's also support for parsing and following links from HTML documents, and it understands the HTTP Link: header.

Using this library it becomes very easy to follow links from a single bookmark, and discover resources and features on the server.

Supported formats:

• HAL
• HTTP Link header - automatically registers as links regardless of format.
• JSON:API - Understands the links object and registers collection members as item relationships.
• application/problem+json - Will extract useful information from the standard problem object and embed them in exception objects.

Following links

One core tenet of building a good REST service, is that URIs should be discovered, not hardcoded in an application. It's for this reason that the emphasis in this library is not on URIs (like most libraries) but on relation-types (the rel) and links.

Generally when interacting with a REST service, you'll want to only hardcode a single URI (a bookmark) and discover all the other APIs from there on.

For example, consider that there is a some API at https://api.example.org/. This API has a link to an API for news articles (rel="articleCollection"), which has a link for creating a new article (rel="new"). When POSTing on that URI, the API returns 201 Created along with a Location header pointing to the new article. On this location, a new rel="author" appears automatically, pointing to the person that created the article.

This is how that interaction might look like:

Coming soon.

Embedded resources

Embedded resources are a HAL feature. In situations when you are modeling a 'collection' of resources, in HAL you should generally just create links to all the items in the collection. However, if a client wants to fetch all these items, this can result in a lot of HTTP requests. HAL uses _embedded to work around this. Using _embedded a user can effectively tell the HAL client about the links in the collection and immediately send along the contents of those resources, thus avoiding the overhead.

Getting understands _embedded and completely abstracts them away. If you use Getting with a HAL server, you can therefore completely ignore them.

For example, given a collection resource with many resources that hal the relationshiptype item, you might use the following API:

Coming soon.

Given the last example, if the server did not use embedding, it will result in a HTTP GET request for every item in the collection.

If the server did use embedding, there will only be 1 GET request.

A major advantage of this, is that it allows a server to be upgradable. Hot paths might be optimized using embedding, and the client seamlessly adjusts to the new information.

Further reading:

• Further reading.
• Hypertext Cache Pattern in HAL spec.

Automatically parsing problem+json

If your server emits application/problem+json documents (RFC7807) on HTTP errors, the library will automatically extract the information from that object, and also provide a better exception message (if the title property is provided).

Documentation

Index

• type Getting
  • func New(b string) (*Getting, error)
  • func (g *Getting) Follow(rt string, v map[string]string) (*resource.Resource, error)
  • func (g *Getting) Go(u string) (*resource.Resource, error)

Types

type Getting

type Getting struct {
	// contains filtered or unexported fields
}

Getting is the core client object. This is the starting point for working with Getting.

func New

func New(b string) (*Getting, error)

New creates a new Getting object.

func (*Getting) Follow

func (g *Getting) Follow(rt string, v map[string]string) (*resource.Resource, error)

Follow is a shortcut for Go.

func (*Getting) Go

func (g *Getting) Go(u string) (*resource.Resource, error)

Go returns a resource by its uri. This function doesnt require a uri if one is not specified, it will return the bookmark resource.