What is halchemy?

Halchemy is a library you use to create client applications - applications that call APIs which use Hypermedia Application Language (HAL).

HAL is an addition to JSON. It is JSON with links^[1]. This combines the data your client needs to know about a resource with links to other related resources, or links to operate the resource itself.

Here is an example of a customer resource, represented in HAL:

{
    "customerId": "A375",
    "givenName": "John",
    "familyName": "Doe",
    "active": false,
    "_links": {
        "self": {
            "href": "/customers/662fbf1eb5442453d30e4d7a"
        },
        "orders": {
            "href": "/customers/662fbf1eb5442453d30e4d7a/orders"
        },
        "activate": {
            "href": "/customers/662fbf1eb5442453d30e4d7a/activate",
            "method": "PUT",
            "_note": "PUT (with no body) to active this customer"
        }
    }
}

How halchemy helps

Let's say your client did a GET request and the above JSON is now in a variable named customer.

With this customer in hand, you may want to:

• POST an order for this customer
• GET the orders this customer has made
• update the customer's name
• activate the customer
• print the customer's name

In a hypermedia application, each of these operations is done by following a link. Let's look at how halchemy improves your client code. These examples only scratch the surface of how halchemy helps.

POST an order

order = {
    'orderNumber': '12345',
    'partNumber': '009343-12',
    'quantity': 3
}  

###############
# Without halchemy (using requests)

# the _links all have relative hrefs, but requests needs an absolute URL
orders_url = urljoin(api_url, customer['_links']['orders']['href'])

# We need to convert the order dict to a JSON string
# and supply the Content-type header
requests.post(update_url, json.dumps(order), 
              headers={'Content-type': 'application/json'})

###############
# With halchemy
api.follow(customer).to('orders').post(order)

NOTE

Sometimes the requests library can infer the JSON string from a dict, but it is a good practice to always convert it like this so you are never caught at runtime with a case where requests does not infer it correctly.

order = {
    orderNumber: '12345',
    partNumber: '009343-12',
    quantity: 3
} 
////////////////
// Without halchemy (using axios)

// assuming axios.defaults.baseURL has been set to the API home URL
axios.post(customer._links.orders.href, order, { 
    headers: { 'Content-type': 'application/json' } 
})

////////////////
// With halchemy
api.follow(customer).to('orders').post(order)

order = {
  "orderNumber" => "12345",
  "partNumber" => "009343-12",
  "quantity" => 3
}

###############
# Without halchemy (using HTTPX)

# the _links all have relative hrefs, but HTTPX needs an absolute URL
def url_join(base, path)
  [base.chomp("/"), path.sub(%r{\A/+}, "")].join("/")
end

url = url_join(api_url, customer["_links"]["orders"]["href"])
HTTPX.with(headers: headers).post(url, json: order)

###############
# With halchemy
api.follow(customer).to("orders").post(order)

GET the orders

###############
# Without halchemy (using requests)

# the _links all have relative hrefs, but requests needs an absolute URL
orders_url = urljoin(api_url, customer['_links']['orders']['href'])

# requests returns an object that contains HTTP details at the top level
# and the resource data inside
response = requests.get(orders_url)
orders = response.json()
for order in orders['_items']:
    print(order['orderNumber'])
    
print(response.status_code)

###############
# With halchemy
#   halchemy operations return resource data at the top level
#   and HTTP details inside
orders = api.follow(customer).to('orders').get()
for order in orders['_items']:
    print(order['orderNumber'])

print(orders._halchemy.response.status_code)

////////////////
// Without halchemy (using axios)

// axios returns an object that contains HTTP details at the top level
// and the resource data inside
response = await axios.get(customer._links.orders.href)
orders = response.data
for (const order of orders._items) {
    console.log(order.orderNumber)
}
console.log(response.status)

////////////////
// With halchemy
//   halchemy operations return resource data at the top level
//   and HTTP details inside
orders = await api.follow(customer).to('orders').get()
for (const order of orders._items) {
    console.log(order.orderNumber)
}
console.log(orders._halchemy.response.status)

###############
# Without halchemy (using HTTPX)

# the _links all have relative hrefs, but requests needs an absolute URL
url = url_join(api_url, customer["_links"]["orders"]["href"])

# HTTPX returns an object that contains HTTP details at the top level
# and the resource data inside
result = HTTPX.get(url)
orders = result.json

orders["_items"].each do |order| 
  puts order["orderNumber"]
end

puts result.status

###############
# With halchemy
#   halchemy operations return resource data at the top level
#   and HTTP details inside
orders = api.follow(customer).to("orders").get()
orders["_items"].each do |order| 
  puts order["orderNumber"]
end

puts orders._halchemy.response.status_code

Update the given name

###############
# Without halchemy (using requests)

# the _links all have relative hrefs, but requests needs an absolute URL
update_url = urljoin(api_url, customer['_links']['self']['href'])  

# This API uses optimistic concurrency control, 
# so we need to supply the If-match header with the Etag from the
# response that we got when we did the GET request for the customer,
# as well as Content-type as before
etag = response.headers['Etag']                               
update_headers = {
    'If-match': etag,
    'Content-type': 'application/json'
}

# We need to convert the update dict to a JSON string
requests.patch(update_url, json.dumps({'givenName': new_name}),
               headers=update_headers)

###############
# With halchemy
api.follow(customer).to('self').patch({'givenName': new_name})

////////////////
// Without halchemy (using axios)

// This API uses optimistic concurrency control,
// so we need to supply the If-match header with the Etag from the
// response that we got when we did the GET request for the customer,
// as well as Content-type as before
const etag = response.headers['Etag']
const updateHeaders = {
    'If-match': etag,
    'Content-type': 'application/json'
}
axios.patch(customer._links.self.href, { givenName: newName }, { headers: updateHeaders })

////////////////
// With halchemy
api.follow(customer).to('self').patch({ givenName: newName })

###############
# Without halchemy (using HTTPX)

# the _links all have relative hrefs, but requests needs an absolute URL
url = url_join(api_url, customer["_links"]["self"]["href"])  

# This API uses optimistic concurrency control, 
# so we need to supply the If-match header with the Etag from the
# response that we got when we did the GET request for the customer,
# as well as Content-type as before
etag = result.headers["Etag"]                               
headers = {
    "If-match": etag,
    "Content-type": "application/json"
}

# We need to convert the update dict to a JSON string
HTTPX.with(headers: headers).patch(url, json: { "givenName" => new_name })

###############
# With halchemy
api.follow(customer).to("self").patch("givenName" => new_name)

Activate the customer

###############
# Without halchemy (using requests)

update_url = urljoin(api_url, customer['_links']['activate']['href'])  
requests.put(update_url, None)

###############
# With halchemy
api.follow(customer).to('activate').put()

////////////////
// Without halchemy (using axios)
axios.put(customer._links.activate.href)

////////////////
// With halchemy
api.follow(customer).to('activate').put()

NOTE

The syntax for this operation not greatly improved when using Javascript compared to other languages. However, even with this simple example there are additional benefits you will see given the fluent approach and given how errors are handled.

###############
# Without halchemy (using requests)

url = url_join(api_url, customer["_links"]["activate"]["href"])  
HTTPX.put(update_url)

###############
# With halchemy
api.follow(customer).to("activate").put

Print the customer's name

###############
# Without halchemy

print(f'Hello {customer["givenName"]}')

###############
# With halchemy - same code
#   halchemy focuses on resource data first
#   and stays out of the way until you need it

print(f'Hello {customer["givenName"]}')

////////////////
// Without halchemy

console.log(`Hello ${customer.givenName}`)

////////////////
// With halchemy - same code
//   halchemy focuses on resource data first
//   and stays out of the way until you need it

console.log(`Hello ${customer.givenName}`)

###############
# Without halchemy

puts "Hello #{customer["givenName"]}"

###############
# With halchemy - same code
#   halchemy focuses on resource data first
#   and stays out of the way until you need it

puts "Hello #{customer["givenName"]}"

These are only a few examples of how halchemy lets your client application more easily make full use of your HAL-based API.

Further reading

• The HAL media type: http://stateless.co/hal_specification.html
• The HAL specification: https://tools.ietf.org/html/draft-kelly-json-hal-08

---

[1] HAL adds links to JSON (application/hal+json) and to XML (application/hal+xml). Halchemy only works with the JSON flavour of HAL.