Assigning of Related Resources

Updating To-One Relationships

A server responds to PATCH, POST requests to a URL from a to-one relationship link as described below.

The PATCH request include a top-level member named data containing one of:

a resource identifier object corresponding to the new related resource.

Use null, to remove the relationship.

For example, the following request updates the Trunk of an DID:

http

PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
 "data": {
   "type": "dids",
   "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
   "relationships": {
     "trunk": {
       "data": { "type": "trunks", "id": "d9b6ec47-0b72-452b-b4b4-23dd9d5be7e6" }
     }
   }
 }
}

curl

curl -i -X PATCH https://api.didww.com/v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c", "relationships": {"trunk": {"data": {"id": "d9b6ec47-0b72-452b-b4b4-23dd9d5be7e6", "type": "trunks"}}}, "type": "dids"}}'

And the following request clears the trunk of the DID:

http

PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

  {
 "data": {
   "type": "dids",
   "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
   "relationships": {
     "trunk": {
       "data": null
     }
   }
 }
}

curl

curl -i -X PATCH https://api.didww.com/v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5", "relationships": {"trunk": {"data": null}}, "type": "dids"}}'

If the relationship is updated successfully then the server returns a successful response.

Updating To-Many Relationships

A server responds to PATCH, POST requests to a URL from a to-many relationship link as described below.

For all request types, the body contain a data member whose value is an empty array or an array of resource identifier objects.

If a client makes a PATCH request to a URL from a to-many relationship link, the server can either completely replace every member of the relationship, return an appropriate error response if some resources can not be found or accessed, or return a 403 Forbidden response if complete replacement is not allowed by the server.

For example, the following request replaces every trunk for an trunk group:

http

PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

   {
  "data": {
    "id": "714e8148-0aea-4cb6-8680-bd1d06453418",
    "type": "trunk_groups",
    "relationships": {
      "trunks": {
        "data": [
          { "type": "trunks", "id": "ca7da6d0-aa0b-447d-8fc0-1bc58b51298c"},
          { "type": "trunks", "id": "e9c1b7e9-253b-46c8-b7e9-5a930ab594c5" }
        ]
      }
    }
  }
}

curl

curl -i -X PATCH https://api.didww.com/v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"id": "714e8148-0aea-4cb6-8680-bd1d06453418", "relationships": {"trunks": {"data": [{"type": "trunks", "id": "ca7da6d0-aa0b-447d-8fc0-1bc58b51298c"}, {"type": "trunks", "id": "e9c1b7e9-253b-46c8-b7e9-5a930ab594c5"}]}}, "type": "trunk_groups"}}'

And the following request clears every trunk for an trunk group:

http

PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

   {
  "data": {
    "id": "c07815fc-bf9e-4cbf-a3fc-9c99b8de14d8",
    "type": "trunk_groups",
    "relationships": {
      "trunks": {
        "data": []
      }
    }
  }
}

curl

curl -i -X PATCH https://api.didww.com/v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' --data-raw '{"data": {"id": "c07815fc-bf9e-4cbf-a3fc-9c99b8de14d8", "relationships": {"trunks": {"data": []}}, "type": "trunk_groups"}}'

If a client makes a POST request to a URL from a relationship link, the server adds the specified members to the relationship unless they are already present. If a given type and id is already in the relationship, the server does not add it again.

If all of the specified resources can be added to, or are already present in, the relationship then the server returns a successful response.