Skip to content

relationships.md

Latest commit

 

History

History
363 lines (323 loc) · 13.6 KB

relationships.md

File metadata and controls

363 lines (323 loc) · 13.6 KB

Relationship Endpoints

Back to the list of all defined endpoints

This endpoint contains the actual relationships connecting 2 items. It uses a relationship type and the 2 items with HAL links

Main Endpoint

/api/core/relationships

A sample can be found at https://dspace7-entities.atmire.com/rest/#https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes

Single Relationship

/api/core/relationships/<:id>

A sample can be found at https://dspace7-entities.atmire.com/rest/#https://dspace7-entities.atmire.com/rest/api/core/relationships/1117

{
  "id": 530,
  "leftPlace": 1,
  "leftwardValue": "Smith, Jane",
  "rightPlace": 1,
  "type": "relationship",
  "_links": {
    "relationshipType": {
      "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/1"
    },
    "self": {
      "href": "https://dspace7-entities.atmire.com/rest/api/core/relationships/530"
    },
    "leftItem": {
      "href": "https://dspace7-entities.atmire.com/rest/api/core/items/e98b0f27-5c19-49a0-960d-eb6ad5287067"
    },
    "rightItem": {
      "href": "https://dspace7-entities.atmire.com/rest/api/core/items/0ffbee3f-e7ea-42bc-92fe-2fbef1a52c0f"
    }
  },
  "_embedded": {
    "relationshipType": {
      "id": 1,
      "leftwardType": "isAuthorOfPublication",
      "rightwardType": "isPublicationOfAuthor",
      "leftMinCardinality": 0,
      "leftMaxCardinality": null,
      "rightMinCardinality": 0,
      "rightMaxCardinality": null,
      "type": "relationshiptype",
      "_links": {
        "leftType": {
          "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/1"
        },
        "rightType": {
          "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
        },
        "self": {
          "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/1"
        }
      },
      "_embedded": {
        "leftType": {
          "id": 1,
          "label": "Publication",
          "type": "entitytype",
          "_links": {
            "self": {
              "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/1"
            },
            "relationshiptypes": {
              "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/1/relationshiptypes"
            }
          }
        },
        "rightType": {
          "id": 2,
          "label": "Person",
          "type": "entitytype",
          "_links": {
            "self": {
              "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
            },
            "relationshiptypes": {
              "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2/relationshiptypes"
            }
          }
        }
      }
    }
  }
}

The relationship type is embedded The 2 items are included as HAL links but are not embedded

An optional leftwardValue and rightwardValue property can be present. It's omitted when it's null.

Creating a relationship

POST /api/core/relationships?relationshipType=<:relationshipType>

A new relationship between 2 items can be created by specifying both items in a uri-list body and specifying the relationshipType as a parameter

A sample CURL command would be:

curl -i -X POST 'https://dspace7-entities.atmire.com/rest/api/core/relationships?relationshipType=1' -H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:text/uri-list" --data 'https://dspace7-entities.atmire.com/rest/api/core/items/12623672-25a9-4df2-ab36-699c4c240c7e \n https://dspace7-entities.atmire.com/rest/api/core/items/5a3f7c7a-d3df-419c-8a2-f00ede62c60a'

Including a name variant would result in:

curl -i -X POST 'https://dspace7-entities.atmire.com/rest/api/core/relationships?relationshipType=1&leftwardValue=Name%20variant%201' -H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:text/uri-list" --data 'https://dspace7-entities.atmire.com/rest/api/core/items/12623672-25a9-4df2-ab36-699c4c240c7e \n https://dspace7-entities.atmire.com/rest/api/core/items/5a3f7c7a-d3df-419c-8a2-f00ede62c60a'

The uri-list should always contain exactly 2 items. The first item will be used as the left Item. The second item will be used as the right Item. The relationshipType parameter is mandatory as well

  • 201 Created - if the operation succeed
  • 401 Forbidden - if you are not authenticated
  • 403 Unauthorized - if you are not logged in with sufficient permissions
  • 422 Unprocessable Entity - if one of the items doesn't exist

Updating the items in a relationship

PUT /api/core/relationships/<:id>/<:leftVsRightItem>

Update the items in the relationship

A sample CURL command to update the left item would be:

curl -i -X PUT 'https://dspace7-entities.atmire.com/rest/api/core/relationships/891/leftItem' -H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:text/uri-list" --data 'https://dspace7-entities.atmire.com/rest/api/core/items/12623672-25a9-4df2-ab36-699c4c240c7e'

A sample CURL command to update the right item would be:

curl -i -X PUT 'https://dspace7-entities.atmire.com/rest/api/core/relationships/891/rightItem' -H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:text/uri-list" --data 'https://dspace7-entities.atmire.com/rest/api/core/items/5a3f7c7a-d3df-419c-8a2-f00ede62c60a'

The uri-list should always contain exactly 1 item. This item will be used as to replace the left of right item, depending on whether the URL ends with /leftItem or /rightItem

The relationshipType is not modifiable

Error codes:

  • 200 OK - if the operation succeeded
  • 401 Forbidden - if you are not authenticated
  • 403 Unauthorized - if you are not logged in with sufficient permissions
  • 404 Not found - if the relationships doesn't exist
  • 422 Unprocessable Entity - if the item doesn't exist, or if the amount of items is not 1

Updating the metadata of a relationship

PUT /api/core/relationships/<:id>

Update the name variant or the place:

curl -i -X PUT 'https://dspace7-entities.atmire.com/rest/api/core/relationships/891' -H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:application/json" --data '{ "leftPlace": 1, "leftwardValue": "Smith, Jane", "rightPlace": 1, "rightwardValue": null }'

Omitted properties will be removed.

Error codes:

  • 200 OK - if the operation succeeded
  • 401 Forbidden - if you are not authenticated
  • 403 Unauthorized - if you are not logged in with sufficient permissions
  • 404 Not found - if the relationship doesn't exist

Relationships per Relationship type

/api/core/relationships/search/byLabel?label=<:relationshipname>

A sample search would be https://dspace7-entities.atmire.com/rest/#https://dspace7-entities.atmire.com/rest/api/core/relationships/search/byLabel?label=isPersonOfOrgUnit The relationshipname parameter is mandatory

It would respond with

{
  "_embedded": {
    "relationships": [
      {
        "id": 590,
        "leftId": "f2235aa6-6fe7-4174-a690-598b72dd8e44",
        "rightId": "d30de96b-1e76-40ae-8ef9-ab426b6f9763",
        "leftPlace": 1,
        "rightPlace": 2,
        "type": "relationship",
        "_links": {
          "relationshipType": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/5"
          },
          "self": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/relationships/590"
          },
          "leftItem": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/items/f2235aa6-6fe7-4174-a690-598b72dd8e44"
          },
          "rightItem": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/items/d30de96b-1e76-40ae-8ef9-ab426b6f9763"
          }
        },
        "_embedded": {
          "relationshipType": {
            "id": 5,
            "leftwardType": "isOrgUnitOfPerson",
            "rightwardType": "isPersonOfOrgUnit",
            "leftMinCardinality": 0,
            "leftMaxCardinality": null,
            "rightMinCardinality": 0,
            "rightMaxCardinality": null,
            "type": "relationshiptype",
            "_links": {
              "leftType": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
              },
              "rightType": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4"
              },
              "self": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/5"
              }
            },
            "_embedded": {
              "leftType": {
                "id": 2,
                "label": "Person",
                "type": "entitytype",
                "_links": {
                  "self": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
                  },
                  "relationshiptypes": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2/relationshiptypes"
                  }
                }
              },
              "rightType": {
                "id": 4,
                "label": "OrgUnit",
                "type": "entitytype",
                "_links": {
                  "self": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4"
                  },
                  "relationshiptypes": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4/relationshiptypes"
                  }
                }
              }
            }
          }
        }
      },
      {
        "id": 589,
        "leftId": "5a3f7c7a-d3df-419c-b8a2-f00ede62c60a",
        "rightId": "c216201f-ed10-4361-b0e0-5a065405bd3e",
        "leftPlace": 2,
        "rightPlace": 1,
        "type": "relationship",
        "_links": {
          "relationshipType": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/5"
          },
          "self": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/relationships/589"
          },
          "leftItem": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/items/5a3f7c7a-d3df-419c-b8a2-f00ede62c60a"
          },
          "rightItem": {
            "href": "https://dspace7-entities.atmire.com/rest/api/core/items/c216201f-ed10-4361-b0e0-5a065405bd3e"
          }
        },
        "_embedded": {
          "relationshipType": {
            "id": 5,
            "leftwardType": "isOrgUnitOfPerson",
            "rightwardType": "isPersonOfOrgUnit",
            "leftMinCardinality": 0,
            "leftMaxCardinality": null,
            "rightMinCardinality": 0,
            "rightMaxCardinality": null,
            "type": "relationshiptype",
            "_links": {
              "leftType": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
              },
              "rightType": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4"
              },
              "self": {
                "href": "https://dspace7-entities.atmire.com/rest/api/core/relationshiptypes/5"
              }
            },
            "_embedded": {
              "leftType": {
                "id": 2,
                "label": "Person",
                "type": "entitytype",
                "_links": {
                  "self": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2"
                  },
                  "relationshiptypes": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/2/relationshiptypes"
                  }
                }
              },
              "rightType": {
                "id": 4,
                "label": "OrgUnit",
                "type": "entitytype",
                "_links": {
                  "self": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4"
                  },
                  "relationshiptypes": {
                    "href": "https://dspace7-entities.atmire.com/rest/api/core/entitytypes/4/relationshiptypes"
                  }
                }
              }
            }
          }
        }
      },
      …
    ]
  },
  "_links": {
    "self": {
      "href": "https://dspace7-entities.atmire.com/rest/api/core/relationships/search/byLabel?label=isPersonOfOrgUnit"
    }
  },
  "page": {
    "number": 0,
    "size": 20,
    "totalPages": 1,
    "totalElements": 2
  }
}

This is similar to https://dspace7-internal.atmire.com/rest/#/rest/api/core/communities/search/subCommunities?parent=daa2657d-5f39-4876-9536-ace42e96b440

It embeds all relationships where the relationship type has the given label on either the left or the right label

This can be further filtered to a single DSO using https://dspace7-entities.atmire.com/rest/#https://dspace7-entities.atmire.com/rest/api/core/relationships/search/byLabel?label=isPersonOfOrgUnit&dso=f2235aa6-6fe7-4174-a690-598b72dd8e44 which contains all relationships created using the relationship type isPersonOfOrgUnit for which one item is f2235aa6-6fe7-4174-a690-598b72dd8e44 The dso parameter is optional

Deleting a relationship

DELETE /api/core/relationships/<:id>

Delete a relationship between 2 items.

A sample CURL command would be:

curl -D - -XDELETE 'https://dspace7-entities.atmire.com/rest/api/core/relationships/890'  -H 'Authorization: Bearer eyJhbGciO…'
  • 204 No content - if the operation succeed
  • 401 Forbidden - if you are not authenticated
  • 403 Unauthorized - if you are not logged in with sufficient permissions
  • 404 Not found - if the relationships doesn't exist (or was already deleted)