/namespaces Resource

Namespaces that are managed by the URN-Service.

GET /namespaces

Returns the registered namespaces. The list can be filtered using the q parameter.

The result 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: 1000, 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 list of namespaces. The format of the filter query is “key:value”. Supported filter keys are name, created, lastmodified, and allowsregistration    
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 fields are name, created and lastmodified name "CREATED" or "LASTMODIFIED" or "NAME"
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)
403 if the current user is not authorised to use a certain search parameter (error code 403001)
Response Body
media type data type description
application/json Collection (JSON) a Collection of {@link RESTNamespaceRepresentation Namespace}s.
Response Headers
name description
Link contains links to the first, last, next and previous result pages

Example

Request
GET /namespaces
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 /namespaces

Creates a new namespace.

Access: System administrators only.

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 CreateNamespaceRequest (JSON) specifies the name of new namespace and additional administrative information.
Response Codes
code condition
201 if the namespace was created successfully
400
  • if not all required fields are provided (error code 400005),
  • if a field was syntactically incorrect (error code 400007) or
  • if the organisation identifier matched no organisation (error code 400009).
401 if the user could not be authenticated (error code 401001)
403 if the user is not allowed to create namespaces (error code 403001)
409 if a namespace with the given name exists already (error code 409001)
Response Body
media type data type description
application/json Namespace (JSON) the new namespace
Response Headers
name description
Location points to the created namespace. Only returned if the request was successful.

Example

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

                
{
  "name" : "urn:nbn:de2112",
  "owner" : "http://example.org/organisations/id/1",
  "urnNamingPolicy" : "http://example.org/policies/urn-naming/id/1",
  "urlPolicy" : "http://example.org/policies/url/id/1",
  "comment" : "This namespace is used for test purposes only",
  "resolverUrl" : "http://example.org/resolver"
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: ...

                
{
  "self" : "http://example.org/namespaces/name/urn:nbn:de:0815",
  "name" : "urn:nbn:de2112",
  "created" : "2017-03-02T15:23:16.123Z",
  "lastModified" : "2017-03-02T15:23:16.123Z",
  "allowsRegistration" : true,
  "comment" : "This namespace is used for test purposes only",
  "resolverUrl" : "http://example.org/resolver",
  "owner" : "http://example.org/organisations/id/1",
  "urnNamingPolicy" : "http://example.org/policies/urn-naming/id/1",
  "urlPolicy" : "http://example.org/policies/url/id/1",
  "urns" : "http://example.org/namespaces/name/urn:nbn:de:0815/urns",
  "urnSuggestion" : "http://example.org/namespaces/name/urn:nbn:de:0815/urnsuggestion"
}