Individual relationships
A relationship joins a source individual to one or more target individuals along a relationship that the ontology declares, such as locatedAt or feeds. The relationship must be declared on the source's class or one of its ancestors, and each target must be an individual of the declared target class. If the relationship is declared to several target classes, a target of any of them is accepted. The Application Ontology Service stores relationships as Item Service relationship records, not as fields on the individual. For more information, see Individual relationships.
This section contains the following API calls:
- List the relationships of an individual
- Add relationships from an individual
- Remove a relationship
- Replace relationships for many individuals
To add many relationships asynchronously, see Add relationships in bulk. To follow relationships across classes, see Traverse relationships between individuals. You can also set relationships when you create or update an individual.
Before you start
These calls share the preconditions of the Individuals API. Every call needs an Authorization: Bearer <token> header and the nsfilter query parameter, and uses the ontology's live version.
- Reading relationships needs
INDIVIDUALS_READon the source's class or an ancestor. Adding, removing, or replacing them needsINDIVIDUALS_EDIT. - Actions are exact-match, so
EDITdoes not implyREAD. To change relationships, you also needREAD, because the service looks up the source and target individuals as you before it writes. - Changing relationships of a lifecycle class (
State,StateTransition,Event,Action) returns403. - If the Item Service refuses a call made with your token, the response is
403, or404if the Item Service returns404.
For the full permission model, see Permissions.
The relationship record
| Field | Type | Description |
|---|---|---|
_userType | String | The name of the declared relationship. |
_relatedToIds | Array | The IDs of the target individuals. |
_customAttributes | Object | A flat map of key-value pairs on the relationship. Values are scalars or arrays of scalars. Declared defaults apply. The service adds its own keys, such as _relationshipId. |
_relatedFromId | String | Output only. The ID of the source individual. |
_relatedUserItemDbId | String | Output only. The ID of the target individuals' collection. |
_relatedUserType | String | Output only. The user type of the target individuals' collection. |
_relationshipId | String | Output only. The ID of the relationship declaration. Omitted if no declaration matches _userType. Don't send it. |
One record holds one source, one _userType, and its targets in one collection. A call with targets in two collections writes two records.
List the relationships of an individual
Lists every relationship record whose source is the individual, including records created directly in the Item Service. This is the only call that returns an individual's relationships.
Endpoints
GET /aosvc/api/v1/classes/{classId}/individuals/{individualId}/relationships
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individual's class. | Required |
individualId | String | The _id of the source individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Response
[
{
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"],
"_customAttributes": {
"installedBy": "crew-7",
"_relationshipId": "0d4e6f8a-2b1c-4d3e-9f5a-7b6c8d0e1f32"
},
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedUserItemDbId": "6702a8e1c1e4b2001f9a1b22",
"_relatedUserType": "room",
"_relationshipId": "0d4e6f8a-2b1c-4d3e-9f5a-7b6c8d0e1f32"
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused to read the individual, usually because you lack READ. |
404 | Not Found. The individual isn't in the class's collection, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Add relationships from an individual
Adds relationships of one type from an individual to one or more target individuals. Targets must already exist. The individual keeps its other relationships of that type. If the individual is already related to a target by this type, the service skips that target.
Endpoints
POST /aosvc/api/v1/classes/{classId}/individuals/{individualId}/relationships
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individual's class. | Required |
individualId | String | The _id of the source individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_userType | String | The name of the relationship, declared on the class or an ancestor. | Required |
_relatedToIds | Array | The IDs of the target individuals. Must not be empty. | Required |
_customAttributes | Object | A flat map of key-value pairs on the relationship. A nested object returns 400. | Optional |
Example:
{
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"],
"_customAttributes": { "installedBy": "crew-7" }
}
Response
The response lists every relationship the individual has after the call, in the same form as List the relationships of an individual. If every target was already related, the call writes nothing and returns 201 with the individual's existing relationships.
[
{
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"],
"_customAttributes": {
"installedBy": "crew-7",
"_relationshipId": "0d4e6f8a-2b1c-4d3e-9f5a-7b6c8d0e1f32"
},
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedUserItemDbId": "6702a8e1c1e4b2001f9a1b22",
"_relatedUserType": "room",
"_relationshipId": "0d4e6f8a-2b1c-4d3e-9f5a-7b6c8d0e1f32"
}
]
Codes
| Code | Description |
|---|---|
201 | Created |
400 | Bad Request. _userType is missing, _relatedToIds is empty, the relationship isn't declared, the declared target class has no collection mapping, a target is missing or of the wrong class, _customAttributes has a nested value, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_EDIT grant, the class is a lifecycle class, or the Item Service refused the read or the write, usually because you lack READ. |
404 | Not Found. The source individual doesn't exist, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
422 | Unprocessable Entity. A functional relationship would have more than one target, counting stored relationships. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Remove a relationship
Removes one relationship from an individual to a target individual.
The call isn't idempotent. If no stored relationship of that type runs from the source to the target, the call returns 404 and writes nothing. Removing the same relationship twice returns 404 the second time.
You need READ as well as INDIVIDUALS_EDIT. The Item Service also checks that you have DELETE permission to remove the relationship record.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/individuals/{individualId}/relationships/{userType}/{targetIndividualId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individual's class. | Required |
individualId | String | The _id of the source individual. | Required |
userType | String | The name of the relationship. | Required |
targetIndividualId | String | The _id of the target individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Response
The response lists the individual's remaining relationships.
[
{
"_userType": "feeds",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1c35"],
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedUserItemDbId": "6702a8e1c1e4b2001f9a1b10",
"_relatedUserType": "pump",
"_relationshipId": "6a8c0e2f-4b3d-4f5e-8a7b-9c1d3e5f7a04"
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The relationship isn't declared on the class or an ancestor, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_EDIT grant, the class is a lifecycle class, or the Item Service refused the call, usually because you lack READ or DELETE there. |
404 | Not Found. The source individual doesn't exist, no such relationship exists, the target isn't an individual of the declared target class, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Replace relationships for many individuals
Sets the relationships of many source individuals of a class in one synchronous call. For each source and _userType pair, the relationships become exactly the targets in _relatedToIds. An empty _relatedToIds removes them. Relationship types you don't name stay unchanged.
The service validates the whole batch before it writes anything. Entries that name the same source and _userType are merged.
Endpoints
PUT /aosvc/api/v1/classes/{classId}/individuals/relationships
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individuals' class. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_relationships | Array | The entries to set. An empty or missing array changes nothing. | Optional |
_relationships[]._relatedFromId | String | The ID of a source individual of this class or its subclasses. | Required |
_relationships[]._userType | String | The name of the relationship. | Required |
_relationships[]._relatedToIds | Array | The complete set of target IDs for this source and relationship. | Required |
This call doesn't accept _customAttributes.
Example:
{
"_relationships": [
{
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"]
},
{
"_relatedFromId": "6702a9f3c1e4b2001f9a1c22",
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40", "6702a9f3c1e4b2001f9a1d41"]
}
]
}
Response
{
"_parentsUpdated": 2,
"_edgesSet": 3
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. An entry is missing _relatedFromId or _userType, a relationship isn't declared, a target is missing or of the wrong class, a source belongs to another class, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_EDIT grant, the class is a lifecycle class, or the Item Service refused the read or the write, usually because you lack READ. |
404 | Not Found. The class isn't in the live version, the Item Service returned 404, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
422 | Unprocessable Entity. A functional relationship would have more than one target. Nothing was written. |
502 | Bad Gateway. The Item Service failed or was unreachable. |