Fetching attribute schemas via the API
Several of the API objects (namely accounts and organisations) contain ‘attributes’ fields. These fields are designed to contain an extendable list of attributes relating to the object.
In order for an API client to obtain a list of the acceptable values for these attributes (for instance to render an input form in a UI), it is possible to query the API for a ‘schema’ object. This object defines acceptable attributes for a given object and additional metadata such as whether such attributes are required (when creating new accounts or organisations).
It is possible to add additional attributes to the schema for your domain. To do this, go to the administration dashboard (https://admin.openthens.net). You need to login as the main administrator for your domain (not a sub-organisation) and go to Preferences > Schema editor. See: Schema editor
Reading an attribute schema
Prerequisites
To query an attribute schema, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain a link to the desired schema object from the entry point resource.
Procedure
Schemas for ‘organisation’ objects may be queried by performing a GET to:
https://admin.openathens.net/api/v1/example.org/schema/organisation
Schemas for ‘account’ objects may be queried by performing a GET to:
https://admin.openathens.net/api/v1/example.org/schema/account/<type>
Where type should be replaced with one of ‘personal’, ‘administrator’ or ‘access’, depending on the desired account type for which the schema applies.
This returns an application/vnd.eduserv.iam.admin.attributeSchema-v1+json
object. This contains a list of ‘attribute definitions’.
Example
Request:
GET /api/v1/example.org/schema/account/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.attributeSchema-v1+json
{
"id" : "7",
"definitions" : [ {
"name" : "username",
"type" : "string",
"displayName" : "Username",
"multiValued" : false,
"required" : false,
"options" : { },
"order" : 1,
"editable" : false
}, {
"name" : "title",
"type" : "string",
"displayName" : "Title",
"multiValued" : false,
"required" : false,
"options" : { },
"order" : 2,
"editable" : true
}, {
... detail omitted
} ],
"links" : [ {
"href" : "/api/v1/example.org/schema/account/personal",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.attributeSchema-v1+json",
"method" : "get"
} ]
}
application/vnd.eduserv.iam.admin.attributeSchema-v1+json object
Object field | Description |
---|---|
name | The name of the attribute. This is the name that should be used to refer to the attribute when performing operations on API objects containing attributes. For instance this forms the key on values in the ‘attribute’ field on account and organisation objects, and their associated error objects. |
displayName | A human-readable name for the attribute. This may be used to label fields on a UI form. |
description | A short description for the attribute. This may be used to provide additional information on a UI (e.g. help text). |
type | The base type of data held in the attribute. |
validateAs | Additional validation that the API will apply to data in addition to the base type. |
multiValued | A Boolean value that defines whether the attribute may hold multiple values. |
required | A Boolean value that defines whether the attribute is mandatory. |
options | Additional options that the API will apply when processing the attribute. Options depend on the attribute type. |
order | The relative order of the attribute in the list of attributes in the complete schema. This may be used to affect the order of fields on a UI input form. |
editable | Whether the attribute is editable via the API. Non-editable attributes may be defined as read-only, or may contain values that are automatically generated by the API and as such cannot be edited directly. |
Standard attributes
Within the OpenAthens system, attributes are definable per domain. All domains will have a standard set of attributes though, listed below. Attributes are not exclusively limited to those appearing in this list – querying the schema for a particular domain may therefore return attributes not shown below. All attributes listed below are optional, unless otherwise stated.
Attribute | Notes | Description |
---|---|---|
username | read-only, unique | The account login name. |
title |
| The title for the user (e.g. Mr, Mrs etc.) |
forenames |
| The user’s first name (required). |
surname |
| The user’s last name (required). |
institution |
| The name of the organisation to which the user belongs (required). |
department |
| The name of the department to which the user belongs. |
position |
| The position (e.g. Job title) of the user. |
emailAddress |
| The email address for the user (required). |
uniqueEmailAddress | unique | A unique email address for the user. This is only required if the user can login with their email address, in which case both this and the emailAddress attribute will be set. |
phone |
| The phone number for the user. |
fax |
| The fax number for the user. |
identifier |
| An additional identifier for the user (e.g. staff number). |
postalAddress |
| The postal address for the user. |
notes |
| Additional notes for the account. |
persistentUID | read-only, unique | An automatically-generated persistent identifier for the account. |
organisationNum | read-only, unique | The nearest parent organisation to the user in the organisation hierarchy. |
See also: