GET from rel

WARNING

This API is frozen and deprecated. Please use the fluent API from 0.9.4 on

Follows a resource's link by way of its rel and sends a GET request.

Signature

The method signature for GET from rel is:

get_from_rel(resource,
             rel: str,
             parameters: dict[str, Any] | None = None,
             template: dict[str, Any] | None = None,
             headers: dict[str, Any] | None = None
             ) -> JSON

JSON: TypeAlias = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None

getFromRel({resource, rel, parameters = {}, template = {}}: RelSpec, headers = {}): Promise<HalResource | {}>

With JavaScript, the first four parameters are actually members of one parameter of type RelSpec, with each being a member of that object.

parameter	description
resource	The body of a response from a previous request, in HAL format
rel	The name of the link relation this GET request will follow.
parameters	(optional) name/value pairs which will be used to create a query string. learn more
template	(optional) if the link is templated, name/value pairs to fill the template. learn more
headers	(optional) add to or override the default headers. learn more
-> returns	the JSON from the payload of the response to this request

Examples

Simple example:

from halchemy import Api

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

root = api.get()  # get the root resource
customers = api.get_from_rel(root, 'customers')

for customer in customers['_items']:
    full_name = f"{customer['givenName']} {customer['familyName']}"
    orders = api.get_from_rel(customer, 'orders')
    order_count = len(orders['_items'])
    print(f'{full_name} has {order_count} {"order" if order_count == 1 else "orders"}')

const {Api} = require('halchemy')

async function listCustomers() {
    const api = new Api('http://example.org/api')

    const root = await api.get()  // get the root resource

    const customers = await api.getFromRel({
        resource: root,
        rel: 'customers'
    })

    for (const customer of customers._items) {
        const fullName = `${customer.givenName} ${customer.familyName}`
        const orders = await api.getFromRel({
            resource: customer,
            rel: 'orders'
        })
        const orderCount = orders._items.length

        console.log(`${fullName} has ${orderCount} ${orderCount == 1? 'order' : 'orders'}`)
    }
}

listCustomers()

The example is based on an API which serves the following:

/

/customers

{ "_links": { "self: { "href": "/" }, "customers": { "href": "/customers" }, "orders": { "href": "/orders" } } }

{ "_items": [ { "membershipId": "A375", "givenName": "Pat", "familyName": "Smith", "active": true, "_links": { "self": { "href": "/customers/A375", }, "edit-form": { "href": "/customers/A375/edit-form", }, "orders": { "href": "/customers/A375/orders", }, "deactivate": { "href": "/customers/A375/deactivate", "_note": "PUT to deactivate" } } }, { "membershipId": "R933", "givenName": "Darcy", "familyName": "Jones", "active": false, "_links": { "self": { "href": "/customers/R933", }, "edit-form": { "href": "/customers/R933/edit-form", }, "orders": { "href": "/customers/R933/orders", }, "activate": { "href": "/customers/R933/activate", "_note": "PUT to activate" } } }, ... ... ... ], "_links": { "self": { "href": "/customers" }, "item": { "href": "/customers/{membershipId}", "templated": true }, "create-form": { "href": "/customers/create-form", } } }

/customers/A375

/customers/A375/orders

{ "membershipId": "A375", "givenName": "Pat", "familyName": "Smith", "active": true, "_links": { "self": { "href": "/customers/A375", }, "edit-form": { "href": "/customers/A375/edit-form", }, "orders": { "href": "/customers/A375/orders", }, "deactivate": { "href": "/customers/A375/deactivate", "_note": "PUT to deactivate this member" } } }

{ "_items": [ { "orderNumber": "FK9384", "partNumber": "009343-12", "quantity": 3, "_customer_ref": "A375", "_links": { "self": { "href": "/orders/65fd80549561b2884948c312", }, "edit-form": { "href": "/orders/65fd80549561b2884948c312/edit-form", }, "parent": { "href": "/customers/A375", }, "collection": { "href": "/customers/A375/orders" } } }, ... ... ... ], "_links": { "self": { "href": "/customers/A375/orders" }, "item": { "href": "/orders/{id}", "templated": true }, "create-form": { "href": "/customers/A375/create-form", } } }