Relating Resources

Resources in OData often have relationships with other resources.
These relationships can be managed through PUT, POST, and DELETE operations.

Adding a Single Relationship

Use HTTP PUT with @odata.id to assign a related entity:

PUT http://myserver:5181/odata/ServiceRequests(139239)/Caller/$ref  HTTP/1.1
Content-Length: 23
Content-Type: application/json


{
    "@odata.id": "http://myserver:5181/odata/Persons(146)"
}

Adding to a Collection

Use HTTP POST to add a new entity to a collection:

POST http://myserver:5181/odata/ServiceRequests(139239)/Workorders/$ref  HTTP/1.1
Content-Length: 23
Content-Type: application/json


{
    "@odata.id": "http://myserver:5181/odata/Workorders(281486108328022)"
}

Adding to a Many-To-Many Collection

Certain properties, like the Members of a Workgroup, have a many-to-many relation. Adding a Member to a Workgroup is the same as adding to a collection:

POST http://myserver:5181/odata/Workgroups(281478224609600)/Members/$ref  HTTP/1.1
Content-Length: 23
Content-Type: application/json


{
    "@odata.id":"http://myserver:5181/odata/Persons(3097165836)"
}

The Users of a Configuration Item (the “CI Users” of Smart Suite) work the same way, from either end. Read them with $expand=Users on a Configuration Item or $expand=UserOfCI on a Person:

POST http://myserver:5181/odata/ConfigurationItems(3098279944)/Users/$ref  HTTP/1.1
Content-Type: application/json


{
    "@odata.id":"http://myserver:5181/odata/Persons(3097165836)"
}
POST http://myserver:5181/odata/Persons(3097165836)/UserOfCI/$ref  HTTP/1.1
Content-Type: application/json


{
    "@odata.id":"http://myserver:5181/odata/ConfigurationItems(3098279944)"
}

Both requests create the same relation.

Relating a Configuration Item to Organizations

The Organizations of a Configuration Item (the “CI Orgs” of Smart Suite) are a many-to-many collection too. Create the relation from either end:

POST http://myserver:5181/odata/ConfigurationItems(3098279944)/Organizations/$ref  HTTP/1.1
Content-Type: application/json


{
    "@odata.id":"http://myserver:5181/odata/Organizations(3097165836)"
}
POST http://myserver:5181/odata/Organizations(3097165836)/ConfigurationItems/$ref  HTTP/1.1
Content-Type: application/json


{
    "@odata.id":"http://myserver:5181/odata/ConfigurationItems(3098279944)"
}

Both requests create the same relation. Repeating a request for entities that are already related succeeds and adds nothing. Read the relation with GET .../ConfigurationItems(3098279944)/Organizations or $expand=Organizations.

Removing a Relationship

To remove a relationship, use HTTP DELETE:

DELETE http://myserver:5181/odata/ServiceRequests(139239)/Caller/$ref  HTTP/1.1

➡ This removes the Caller reference, leaving it empty.

Removing from a Collection

For collections, name the entity to remove with the $id query option, as OData 4.0 specifies:

DELETE http://myserver:5181/odata/ServiceRequests(3101097999)/Workorders/$ref?$id=http://myserver:5181/odata/Workorders(281486108328022)  HTTP/1.1

The key of the entity can also be given in the path instead:

DELETE http://myserver:5181/odata/ServiceRequests(3101097999)/Workorders(281486108328022)/$ref  HTTP/1.1

➡ Both remove Workorder (281486108328022) from ServiceRequest (3101097999). The second form is an extension; see OData 4.0 Conformance Notes.

Nested Relationships

The same approach applies to nested references within complex properties:

http://myserver:5181/odata/ServiceRequests(139239)/Assignment/AssigneeWorkgroup/$ref
http://myserver:5181/odata/ServiceRequests(139239)/Assignment/AssigneePerson/$ref

Notes

  • PUT / POST → assign a relationship.
  • DELETE → remove a relationship.
  • A successful request returns 204 No Content. A Prefer header does not change this; to see the result, GET the resource afterwards.
Back to top