GET from rel with lookup

WARNING

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

Identical to GET from rel, but uses an implicit URL template - if the API is so configured.

This method is seldom used, and was only created here to take advantage of hypermea's "additional lookup" field. It allows a resource in the API to designate one field that can be used to look up an item. It requires the client know which field is so designated, and thus violates strict adherence to the "no out of band knowledge" constraint.

NOTE: only GET can use the implicit template of a lookup field. If you need to send a different request, follow the self rel (e.g. patch_resource(the_resource, 'self')).

Signature

The method signature for GET from rel with lookup is:

get_from_rel_with_lookup(resource,
             rel: str,
             lookup: 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

getFromRelWithLookup({resource, rel, parameters = {}, template = {}}: RelSpec, lookup: string, 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. If not supplied, the default is self
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
lookup	The value of the "additional lookup" field to GET
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
customer = api.get_from_rel_with_lookup(root, 'customers', 'A375')

print(f"{customer['givenName']} {customer['familyName']} is {'active' if customer['active'] else 'inactive'}")

const {Api} = require('halchemy')

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

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

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

    console.log(`${customer.givenName} ${customer.familyName} is ${customer.active? 'active' : 'inactive'}`)
}

listMember('A375')

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", } } }