Skip to content

Latest commit

 

History

History
319 lines (264 loc) · 12 KB

epersons.md

File metadata and controls

319 lines (264 loc) · 12 KB
Raw

EPersons Endpoints

Back to the list of all defined endpoints

Main Endpoint

GET /api/eperson/epersons

Single EPerson

GET /api/eperson/epersons/<:uuid>

{
  "id": "028dcbb8-0da2-4122-a0ea-254be49ca107",
  "uuid": "028dcbb8-0da2-4122-a0ea-254be49ca107",
  "name": "user@institution.edu",
  "handle": null,
  "metadata": {
      "eperson.firstname": [
        {
          "value": "John",
          "language": null,
          "authority": "",
          "confidence": -1,
          "place": 0
        }
      ],
      "eperson.language": [
        {
          "value": "en",
          "language": null,
          "authority": "",
          "confidence": -1,
          "place": 0
        }
      ],
      "eperson.lastname": [
        {
          "value": "Doe",
          "language": null,
          "authority": "",
          "confidence": -1,
          "place": 0
        }
      ]
  },
  "netid": null,
  "lastActive": "2019-09-25T15:59:28.000+0000",
  "canLogIn": true,
  "email": "user@institution.edu",
  "requireCertificate": false,
  "selfRegistered": true,
  "machineTokenGenerated": true,
  "type": "eperson",
  "_links": {
    "self": {
      "href": "https://demo.dspace.org/server/api/eperson/epersons/028dcbb8-0da2-4122-a0ea-254be49ca107"
    },
    "groups": {
      "href": "https://demo.dspace.org/server/api/eperson/epersons/028dcbb8-0da2-4122-a0ea-254be49ca107/groups"
    }
  }
}

Search methods

byEmail

/api/eperson/epersons/search/byEmail?email=<:string>

The supported parameters are:

  • email: mandatory, EPerson's email to search

It returns the EPersonRest instance, if any, matching the user query

Return codes:

  • 200 OK - if the operation succeed
  • 400 Bad Request - if the email parameter is missing or invalid
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators and users with READ rights on the target EPerson can use the endpoint

byMetadata

GET /api/eperson/epersons/search/byMetadata?query=<:string>

This supports a basic search across all EPerson accounts via their metadata. It will search in:

  • UUID (exact match)
  • first name
  • last name
  • email address

It returns the list of EPersonRest instances, if any, matching the user query

Return codes:

  • 200 OK - if the operation succeed
  • 400 Bad Request - if the 'query' parameter is missing or invalid
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.

isNotMemberOf

GET /api/eperson/epersons/search/isNotMemberOf?group=<:uuid>&query=<:string>

This supports a basic search across all EPersons which are not already a member of the provided Group (in the 'group' parameter). Therefore it searches EPersons not already listed on the /api/eperson/groups/<:uuid>/epersons endpoint for the provided group. It will search in:

  • UUID (exact match)
  • first name
  • last name
  • email address

It returns the list of EPersonRest instances, if any, matching the user query

Return codes:

  • 200 OK - if the operation succeed
  • 400 Bad Request - if the 'group' or 'query' parameter is missing or invalid
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.

Patch operations

EPerson metadata can be modified as described in Modifying metadata via Patch.

Additional properties can be modified via Patch as described below.

Replace

The replace operation allows to replace existent information with new one. Attempt to use the replace operation to set not yet initialized information must return an error. See general errors on PATCH requests

These operations can be performed by administrators.

To replace the certificate required value, curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson> -H "Content-Type: application/json" -d '[{ "op": "replace", "path": "/certificate", "value": "true|false"]'. The operation also requires an Authorization header.

For example, starting with the following eperson field data:

 "requireCerticate": true,

the replace operation [{ "op": "replace", "path": "/certificate", "value": "false"] will result in :

  "requireCerticate": false,

To replace the canLogin value, curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson> -H "Content-Type: application/json" -d '[{ "op": "replace", "path": "/canLogin", "value": "true|false"]'. The operation also requires an Authorization header.

For example, starting with the following eperson field data:

 "canLogIn": true,

the replace operation [{ "op": "replace", "path": "/canLogin", "value": "false" will result in :

  "canLogIn": false,

To replace the netid value, curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson> -H "Content-Type: application/json" -d '[{ "op": "replace", "path": "/netid", "value": "newNetId"]'. The operation also requires an Authorization header.

For example, starting with the following eperson field data:

 "netid": "oldNetId",

the replace operation [{ "op": "replace", "path": "/netid", "value": "newNetId"] will result in :

  "netid": "newNetId",

To replace the email value, curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson> -H "Content-Type: application/json" -d '[{ "op": "replace", "path": "/email", "value": "new@email"]'. The operation also requires an Authorization header.

For example, starting with the following eperson field data:

 "email": "old@email",

the replace operation [{ "op": "replace", "path": "/email", "value": "new@email"] will result in :

  "email": "new@email",

These operations can be performed by administrators and by the authenticated user.

The currently authenticated user can modify their EPerson metadata. An administrator can modify any EPerson's metadata.
This includes, but is not limited to, last name, first name, phone, language

Add

The add operation allows adding or replacing information in the EPerson. Password changes are currently required to use "add" requests.

These operations can be performed by administrators and by the authenticated user.

To add/replace the password value while authenticated, use curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson> -H "Content-Type: application/json" -d '[{ "op": "add", "path": "/password", "value": {"new_password": "newpassword", "current_password":"oldpassword"}}]'.
To add/replace the password value based on a registration token, use curl -X PATCH http://${dspace.url}/api/eperson/epersons/<:id-eperson>?token=<:token> -H "Content-Type: application/json" -d '[{ "op": "add", "path": "/password", "value": {"new_password": "newpassword"}}]'.
The operation requires an Authorization header or a token.

If the provided current_password is wrong, a response with status 403 Forbidden is returned.

For example, starting with the following eperson field data:

 "password": "oldpassword",

the replace operation [{ "op": "add", "path": "/password", "value": {"new_password": "newpassword", "current_password":"oldpassword"}}] will result in :

  "password": "newpassword",

Status codes:

  • 422 Unprocessable Entity - If the provided password not respects the rules configured in the regular expression

NOTE: The new password is currently returned after an update but this could be revisited later, see #30

Create new EPerson (requires admin permissions)

POST /api/eperson/epersons

To create a new EPerson, perform a post with the JSON below to the epersons endpoint when logged in as admin.

{
  "name": "user@institution.edu",
  "metadata": {
    "eperson.firstname": [
      {
        "value": "John",
        "language": null,
        "authority": "",
        "confidence": -1
      }
    ],
    "eperson.lastname": [
      {
        "value": "Doe",
        "language": null,
        "authority": "",
        "confidence": -1
      }
    ]
  },
  "canLogIn": true,
  "email": "user@institution.edu",
  "requireCertificate": false,
  "selfRegistered": true,
  "type": "eperson"
}

Status codes:

  • 201 Created - if the operation succeed
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions
  • 422 Unprocessable Entity - if the email address was omitted or already exists

Create new EPerson based on registration token

POST /api/eperson/epersons?token=<:token>

To create a new EPerson, perform a post with the JSON below to the epersons endpoint while including a token. The token will be sent via Email from the Create new EPerson registration.

{
  "metadata": {
    "eperson.firstname": [
      {
        "value": "John",
        "language": null,
        "authority": "",
        "confidence": -1
      }
    ],
    "eperson.lastname": [
      {
        "value": "Doe",
        "language": null,
        "authority": "",
        "confidence": -1
      }
    ]
  },
  "canLogIn": true,
  "requireCertificate": false,
  "type": "eperson"
}

The "eperson.firstname" and "eperson.lastname" metadata are mandatory. The phone number, language, … are optional metadata.
The email property can be set, but would need to be identical to the value from the registration.
The selfRegistered property can be set, but would need to be true If the token is associated with invitation to join one or more groups the created eperson will be enrolled in such group upon creation.

Status codes:

  • 201 Created - if the operation succeed
  • 400 Bad Request - if the email address didn't match the token or already exists. If the token doesn't exist or is expired
  • 401 Unauthorized - if the token doesn't allow you to create this account
  • 422 Unprocessable Entity - If the provided password not respects the rules configured in the regular expression

Merge eperson registration data

POST /api/eperson/epersons/<:uuid>?token=<:token>&override=<:metadata-fields>

Allows the merge of some registrationData related to the provided registration-token (i.e. <:token>) into an already actived user account. This action is permitted by:

  • logged-user: that has the same uuid as the one specified with the <:uuid> param.
  • anonymous-user: that provides a validation-token (i.e. a token obtained via email confirmation)

The override parameter contains the list of metadata-fields that will be overwritten for that linked user.

The token was previously sent via Email from the Create new EPerson registration.

This example shows a simlpe request:

curl -X POST http://${dspace.url}/api/eperson/epersons/${id-eperson}?token=${token}&override=${metadata-fields} \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${bearer-token}" \

As you can see, the request has an empty body.

Status codes:

  • 201 Created - if the operation succeed
  • 400 Bad Request - if the uuid provided doesn't exist, or if some override element isn't found inside the linked user item.
  • 401 Unauthorized - The user is anonymous, the uuid of the user is not the same as the one logged in, or if the token is not valid (i.e. expired or wrong type).
  • 403 Forbidden - The user is authenticated, the token is not valid or the uuid is not the same as the one of the user.

Linked entities

Groups

GET /api/eperson/epersons/<:uuid>/groups

A HAL link to retrieve the eperson groups of an eperson is included. This will return a pageable list of the groups this person is a direct member of

TODO: A solution to retrieve direct and indirect groups of an eperson is also required. This would use GroupService.allMemberGroupsSet() and is used e.g. when viewing an EPerson as an admin