Persistent Uniform Resource Locator Service
Persistent Uniform Resource Locator Service

About

The Persistent Uniform Resource Locator (PURL) service provides methods for creating, updating, and managing PURLs in RUcore. Currently this service supports Digital Object Identifiers (DOIs).

The base URL for our PURL service is

Responses

Responses are formed in XML or plain text depending on the method being used. Further detail can be found under each methods documentation.

Digital Object Identifier (DOI) Requests

We currently offer the following DOI related methods. The extension under the PURL service URL for accessing DOI methods is doi. These methods will operate using the following shoulder(s):
  • doi:10.5072/FK2
  • doi:10.7282/T3

Methods

  • Create
  • Delete
  • Identifier State
  • System Status
  • Update
  • Verify

Create

Top

An identifier will be "created" based on the information provided. If a suffix is not provided, a suffix will be minted or generated. By default all identifiers will be created with a state set to "reserved" and "export" set to no.

HTTP Method

POST

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/create/

Restricted

Authorization key required

Arguments

  • id : string
    required Unique identifier of the item in the repository
  • key : string
    required Authorization key
  • suffix : string
    optional A unique suffix to use when registering the DOI. If not provided an opaque identifier will be minted/generated.

Sample Response

The presence of a <status_code> with a value of 201 signals a successful request. The new identifiers are in the <doi> and <ark> sub-elements to the <response> element.

Sample Error

When an error occurs the <status_code> will provide a value other than 201. These <status_code> values are based on HTTP Status Codes. An <error> sub-element containing a helpful message will also be provided.

Delete

Top

Deletes an identifier if its state is "reserved."

HTTP Method

DELETE

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/delete/

Restricted

Authorization key required

Arguments

  • id : string
    required Unique identifier of the item in the repository or a DOI managed under the shoulder this service is provided.
  • key : string
    required Authorization key

Sample Response

The presence of a <status_code> with a value of 200 signals a successful request. The <success> sub-element provides a message as to what was deleted.

Sample Error

When an error occurs the <status_code> will provide a value other than 200. These <status_code> values are based on HTTP Status Codes. An <error> sub-element containing a helpful message will also be provided.

Identifier State

Top

Either reports the current state of an identifier or changes the state of an identifier. When changing the state of an identifier to "public" the export flag at the registrar will be set to "yes." When setting an identifier to "unavailable" the export flag will be set to "no."

HTTP Method

POST

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/state/

Restricted

Authorization key required.

Arguments

  • id : string
    required Unique identifier of the item in the repository or a DOI managed under the shoulder this service is provided.
  • key : string
    required Authorization key
  • action : string, enumerated (current, update)
    required Passing a value of "current" reports the current state of the DOI at the provider. Passing a value of "update" will change the current state of the DOI to the value specified by the state argument.
  • state : string, enumerated (public, unavailable)
    conditional This argument is required when passing an action argument set to "update". Acceptable values are "public" and "unavailable." Only identifiers that are currently marked as "public" can be changed to "unavailable." When an identifier is initially created it's default state is "reserved" and its state can only be changed to "public."
  • reason : string
    optional When updating a DOI to a state of "unavailable" a reason can be attached. This reason will be displayed when visiting the DOI tombstone page.

Sample Response (action=current)

The presence of a <status_code> with a value of 200 signals a successful request. The <state> sub-element provides a current state of the identifier; reserved, public or unavailable.

Sample Error (action=current)

When an error occurs the <status_code> will provide a value other than 200. These <status_code> values are based on HTTP Status Codes. An <error> sub-element containing a helpful message will also be provided.

Sample Response (action=update)

The presence of a <status_code> with a value of 200 signals a successful request. The <success> sub-element provides a helpful message.

Sample Error (action=update)

When an error occurs the <status_code> will provide a value other than 200. These <status_code> values are based on HTTP Status Codes. An <error> sub-element containing a helpful message will also be provided.

When metadata requirements have not been satisfied the state of a DOI cannot be changed. In this case it is recommended that the Update method be run before attempting to change the state of the DOI.

Metadata

Top

If the source is set to "repository" this method generates metadata suitable for the DOI registrar. When the source is set to "registrar" the currently stored metadata at the registrar is retrieved and returned.

HTTP Method

POST

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/metadata/

Restricted

Authorization key required.

Arguments

  • id : string
    required Unique identifier of the item in the repository when source is "repository", DOI when the source is set to "registrar"
  • key : string
    required Authorization key
  • source : string, enumerated (repository, registrar)
    required Source of the metadata

Sample Response (source=repository)

On a successful request the metadata is returned in plain text with individual lines for each metadata element.

Sample Error (source=repository)

When an error occurs the <status_code> will be 400. An <error> sub-element containing a helpful message will also be provided.

Sample Response (source=registrar)

On a successful request the metadata is returned in plain text with individual lines for each metadata element.

Sample Error (source=registrar)

When an error occurs the <status_code> will provide a value of 400. An <error> sub-element containing a helpful message will also be provided.

System Status

Top

Reports the current status of the DOI provider and/or a subsystem.

HTTP Method

GET

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/status/{subsystem}

Arguments

  • subsystem : string
    optional Name of a particular DOI subsystem you would like the status of. Using the wildcard(*) all subsystem statuses will be returned.

Sample Response

The presence of a <status_code> with a value of 200 signals a successful request. The <success> sub-element provides a helpful message.

Sample Error (source=repository)

When an error occurs the <status_code> will be 400. An <error> sub-element containing a helpful message will also be provided.

Update

Top

Updates metadata at the registrar for a given repository resource.

HTTP Method

POST

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/update/

Restricted

Authorization key required.

Arguments

  • id : string
    required Unique identifier of the item in the repository
  • key : string
    required Authorization key

Sample Response

The presence of a <status_code> with a value of 200 signals a successful request. The <success> sub-element provides a helpful message.

Sample Error (source=repository)

When an error occurs the <status_code> will be 400. An <error> sub-element containing a helpful message will also be provided.

Verify

Top

Tests a repository resource is registered properly by comparing the DOI stored in the resources metadata with the actual DOI response.

HTTP Method

GET

URI

https://rucore.libraries.rutgers.edu/api/purl/doi/verify/{id}

Arguments

  • id : string
    required Unique identifier of the item in the repository

Sample Response

The presence of a <status_code> with a value of 200 signals a successful request. The <success> sub-element provides a helpful message.

Sample Error

When an error occurs the <status_code> will be 400. An <error> sub-element containing a the repository <target> and <doi> for the resource are returned to aid further troubleshooting.

Background

RUcore has been developing web services that allow software applications to easily interact with our repository framework of services. These web services are REST based and typically respond to requests in XML or JSON.

Web Services

Listserv and Google Group

A listserv has been established that will be used to communicate service outages and RUcore web service related news. The listserv address is rucore_web_services[at]email.rutgers.edu. Visit this page to subscribe.

A Google Group has been created to provide a place for discussion about the web services RUcore provides.

If you have any further questions please contact us.
Version 8.2.5
Rutgers University Libraries - Copyright ©2017