Tenants

The Tenants resource contains a list of all the registered EMu environments. Tenants are defined in the restapi/conf/tenants.conf configuration file and read by the shim when it starts up. See Tenants Configuration for more details about how an EMu environment is configured as a tenant in the shim. The JSON below shows the information available about a tenant:

{
    "id": "emu:/shared/tenants/museum",
    "version": 1,
    "data": {
        "tenant": "museum",
        "authentication": "pam",
        "pam": {
            "service": "texpress"
        },
        "token": {
            "signingKey": "****************",
            "timeout": 900
        },
        "organisation": {
            "legalName": "The National Museum",
            "address": {
                "addressLocality": "Washington",
                "addressRegion": "DC",
                "addressCountry": "USA"
            }
        }
    }
}

The properties are defined as:

Name	Description
tenant	Name of the tenant used in URL based requests
authentication	Type of authentication service used. EMu uses “pam” for authentication
pam	Information about PAM configuration
pam/service	Name of the pam service used for authentication
token	Information about token characteristics
token/signingKey	Private shared key used to sign JWT tokens. The actual key is never output, but is defined in the restapi/conf/tenants.conf file.
token/timeout	Seconds a token is valid before expiring. The expiry time is reset each time the token is used
organisation	Information about the institution associated with the tenant
organisation/legalName	Official name
organisation/email	Contact email address
organisation/url	URL of home page
organisation/address	Physical address location of institution
organisation/address/streetAddress	Number and street name
organisation/address/postalCode	Postcode or zipcode
organisation/address/addressLocality	City or town
organisation/address/addressRegion	State or province
organisation/address/addressCountry	Country

The list of tenants is system wide so the shared tenant name is used along with the tenants resource to interact with the resource.

The following requests are supported by the tenants resource.

Update

PATCH /shared/tenants

The list of available tenants is read in by the shim from the restapi/conf/tenants.conf configuration file. When a new tenant is added to the file the shim must be either restarted or requested to re-load the tenant’s file. The PATCH /shared/tenants request forces the shim to re-read the tenant’s file loading any new tenants and discarding any removed tenants. The request can only be made by the system admin user as defined by the admin setting in the restapi/conf/restapi.conf file. Once the tenants have been re-loaded a list of the new tenants is returned.

Example URI

PATCH /shared/tenants

Headers

Authorization: Bearer {token}
Prefer: representation=minimal

Response 200

{
    "@namespaces": {
        "emu": {
            "name": "http://axiell.com/emu#"
        }
    },
    "@controls": {
        "self": {
            "href": "http://swanston.melbourne.axiell.com:8084/shared/tenants"
        },
        "start": {
            "method": "GET",
            "href": "http://swanston.melbourne.axiell.com:8084/"
        },
        "search": {
            "method": "GET",
            "href": "http://swanston.melbourne.axiell.com:8084/shared/tenants"
        },
        "emu:update-all": {
            "method": "PATCH",
            "href": "http://swanston.melbourne.axiell.com:8084/shared/tenants",
            "encoding": "json",
            "schemaUrl": "http://json.schemastore.org/json-patch"
        }
    },
    "hits": 2,
    "matches": [
        {
            "id": "emu:/shared/tenants/museum",
            "version": 1,
            "data": {
                "tenant": "museum",
                "authentication": "pam",
                "pam": {
                    "service": "texpress"
                },
                "token": {
                    "signingKey": "****************",
                    "timeout": 900
                },
                "organisation": {
                    "legalName": "The National Museum",
                    "address": {
                        "addressLocality": "Washington",
                        "addressRegion": "DC",
                        "addressCountry": "USA"
                    }
                }
            },
            "@controls": {
                "self": {
                    "href": "http://swanston.melbourne.axiell.com:8084/shared/tenants/museum"
                }
            }
        },
        {
            "id": "emu:/shared/tenants/mv",
            "version": 1,
            "data": {
                "tenant": "mv",
                "authentication": "pam",
                "pam": {
                    "service": "texpress"
                },
                "token": {
                    "signingKey": "****************",
                    "timeout": 1800
                }
            },
            "@controls": {
                "self": {
                    "href": "http://swanston.melbourne.axiell.com:8084/shared/tenants/mv"
                }
            }
        }
    ]
}

Response Headers

Content-Type: application/vnd.mason+json; charset=UTF-8
Authorization: Bearer {token}

Retrieve

GET /shared/tenants[?select={selectlist}]
GET /shared/tenants/{tenant}[?select={selectlist}]

The GET method retrieves information about registered tenants. The first form returns a matches array containing all the tenants registered for use by shim. The second form provides information about a single tenant. A 200 status is returned if the requested tenant exists otherwise a 404 status is returned. Only the administrator account can retrieve information about tenants. The name of the administrator account can be found in the restapi/conf/restapi.conf file under the admin setting.

By default all values in the record are returned. You can limit the values returned using the select query parameter. The parameter takes a comma separated list of field names. The field names are that of the enveloped record so most field names will start with data.. The Select Syntax section provides a complete description of acceptable values for the select query parameter.

Example URI

GET /shared/tenants/museum

Headers

Authorization: Bearer {token}
Prefer: representation=minimal

Response 200

{
    "id": "emu:/shared/tenants/museum",
    "version": 1,
    "data": {
        "tenant": "museum",
        "authentication": "pam",
        "pam": {
            "service": "texpress"
        },
        "token": {
            "signingKey": "****************",
            "timeout": 900
        },
        "organisation": {
            "legalName": "The National Museum",
            "address": {
                "addressLocality": "Washington",
                "addressRegion": "DC",
                "addressCountry": "USA"
            }
        }
    }
}

Response Headers

Content-Type: application/vnd.mason+json; charset=UTF-8
Authorization: Bearer {token}