Embedded content

Work in progress

This warning will be removed once this page has passed testing.

Let's take a look at this resource model:

A simple Library resource model

tl;dr

from halchemy import Api

api = Api('http://example.org/api')
home = api.home.get()
member_collection = api.follow(home).to('member').get()

# Use default embedded resource collection
for member in member_collection.embedded('member'):
    ...

# Fetch a member AND the books that member has borrowed
member = (api.follow(member_collection)
             .to('item')
             .with_template_values({'id': '67ea8978864962ce925a319e'})
             .with_parameters({'embed': 'book'})
             .get()
         )
         
print(f'{member["name"]} has borrowed the following books:')
for book in member.embedded('book'):
    print(f'- book["title"]')

import { Api } from 'halchemy'

const api = new Api('http://example.org/api')
const home = await api.home.get()

// Use default embedded resource collection
const memberCollection = await api.follow(home).to('member').get()
for (const m of memberCollection.embedded('member')) {
    ...
}

// Fetch a member AND the books that member has borrowed
const member = await api.follow(memberCollection)
                        .to('item')
                        .withTemplateValues({id: '123'})
                        .withParameters({embed: 'book'})
                        .get()
console.log(`${member.name} has borrowed the following books:`)
for (const book in member.embedded('book')) {
    console.log(`- ${book.title}`)
}

require "halchemy"

api = Halchemy::Api.new "http://example.org/api"
home = api.home.get

# Use default embedded resource collection
member_collection = api.follow(home).to('member').get()
member_collection.embedded('member').each do |member|
  ...
end

# Fetch a member AND the books that member has borrowed
member = api.follow(member_collection).
             to('item').
             with_template_values({'id': '67ea8978864962ce925a319e'}).
             with_parameters({'embed': 'book'}).
             get
puts "#{member["name"]} has borrowed the following books:"   
member.embedded("book").each do |book|
    puts "- #{book["title"]}"
end

Deeper walkthrough

Work in progress

When we get the home resource...

from halchemy import Api

api = Api('http://example.org/api')
home = api.home.get()

import { Api } from 'halchemy'

const api = new Api('http://example.org/api')
const home = api.home.get()

require "halchemy"

api = Halchemy::Api.new "http://example.org/api"
home = api.home.get

...we get back:

{
    "_links": {
        "self": {
            "href": "/",
            "_note": "Home resource for library system"
        },
        "library": {
            "href": "/libraries{?links_only}",
            "templated": true
        },
        "member": {
            "href": "/members{?links_only}",
            "templated": true
        },
        "book": {
            "href": "/books{?links_only}",
            "templated": true
        }
    }
}

Each of these resources is a collection, i.e. there are many libraries, each with many members, holding many books, etc.

When a HAL-oriented API serves a collection resource, the actual list is found in the _embedded property.

For example this call...

member_collection = api.follow(home).to('member').get()
print(json.dumps(member_collection, indent=4))

const memberCollection = api.follow(home).to('member').get()
console.log(JSON.stringify(memberCollection, null, 4))

member_collection = api.follow(home).to('member').get()
puts JSON.pretty_generate member_collection

The JSON representation of the member collection is as follows:

{
  "_links": {
    "self": { "href": "/members"  },
    "item": {
      "href": "/members/{id}",
      "templated": true
    },
    "search": {
      "href": "/members{?where,sort,max_results,page,embed}",
      "templated": true
    },
    ...
  },
  "_meta": {
    "page": 1,
    "max_results": 1000,
    "total": 6
  },
  "_embedded": {
    "member": [
      {
        "_id": "67ea066d1dd141f4499b9528",
        "name": "John Doe",
        "_links": {
          "self": { "href": "/members/67ea066d1dd141f4499b9528" },
          "book": { "href": "/members/67ea066d1dd141f4499b9528/books" },
          ...
        }
      },
      {
        "_id": "67ea06741dd141f4499b9529",
        "name": "Sally Jane",
        "_links": {
          "self": { "href": "/members/67ea06741dd141f4499b9529" },
          "book": { "href": "/members/67ea06741dd141f4499b9529/books" },
          ...
        }
      },
      ...
      ...
    ]
  }
}