/urns Resource

URNs managed by the URN-Service.

GET /urns

Returns all registered URNs. The result set can be filtered using the q parameter.

The result set is paged. The count and offset parameters can be used to navigate through the result list. Alternatively, the Link header contains URLs for browsing through the result list.

Access: Unauthorized (public) access allowed.

Request Parameters
name type description default constraints
count query number of entries to return. Maximum is 1000, default is 20. 20 max: 20, min: 0
offset query index of the first entry to return starting from 0. Default is 0. 0 min: 0
q query allows to filter the result set. The format of the filter query is “key:value”. Supported filter keys are urn, creationdate and lastmodified    
runas query optional login name whose identity is used to execute the request (only available to users with the RunAs privilege)    
sortby query sort field. Supported field are urn, creationdate and lastmodified urn "CREATED" or "LASTMODIFIED" or "URN"
sortorder query sort order. Must be either asc or desc asc "ASC" or "DESC"
Response Codes
code condition
200 if the request was completed successfully
400
  • if the search query was not valid (error code 400001) or
  • a parameter had an unsupported value (error code 400004)
401 if the user could not be authenticated (error code 401001)
Response Body
media type data type description
application/json Collection (JSON) a collection cof Urns
Response Headers
name description
Link contains links to the first, last, next and previous result pages

Example

Request
GET /urns
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
Link: ...

                
{
  "self" : "http://example.org/collection",
  "totalItems" : 42,
  "items" : [ { }, { } ]
}

POST /urns

Registers a new URN.

Access: Namespace owners only for their own namespaces.

Request Parameters
name type description
runas query optional login name whose identity is used to execute the request (only available to users with the RunAs privilege)
Request Body
media type data type description
application/json CreateUrnRequest (JSON) the registration details for the new URN
Response Codes
code condition
201 if the URN was registered successfully
400
  • if mandatory fields are missing in the request (error code 400005),
  • if a field is not valid (error code 400007),
  • if no namespace matching the prefix exists (error code 400009) or
  • if the URN does not pass format validation (error code 40010).
401 if the user is not authenticated (error code 401001)
403 if the user is not authorized to register
  • URNs (error code 403001)
  • or URNs in inactive namespaces (error code 403001)
409 if there the URN already exists (error code 409001)
Response Body
media type data type description
application/json Urn (JSON) the registration information of the new URN
Response Headers
name description
Location URI pointing to the new URN

Example

Request
POST /urns
Content-Type: application/json
Accept: application/json

                
{
  "urn" : "urn:nbn:de:101:1-200911171195",
  "urls" : [ {
    "url" : "http://example.org/the-document.pdf",
    "owner" : "http://example.org/organisations/id/1516",
    "priority" : 100
  }, {
    "url" : "http://example.org/the-document.pdf",
    "owner" : "http://example.org/organisations/id/1516",
    "priority" : 100
  } ]
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: ...

                
{
  "self" : "http://example.org/urns/urn/urn:nbn:de:101:1-200911171195",
  "urn" : "urn:nbn:de:101:1-200911171195",
  "created" : "2017-03-02T15:23:16.123Z",
  "lastModified" : "2017-03-02T15:23:16.123Z",
  "namespace" : "http://example.org/namespaces/name/urn:nbn:de:101:1",
  "successor" : "http://example.org/urns/urn/urn:nbn%3Ade:101:1-20112061111",
  "urls" : "http://example.org/urns/urn/urn:nbn:de:101:1-200911171195/urls",
  "myUrls" : "http://example.org/urns/urn/urn:nbn:de:101:1-200911171195/my-urls"
}