/organisations Resource

Organisations and contacts who manage their URNs and URLs with the URN-Service.

GET /organisations

Returns the registered organisations. 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 organisations. The format of the filter query is “key:value”. Supported filter keys are name, created, lastmodified, address.street, address.postcode, address.city and comment    
runas query optional login name whose identity is used to execute the request (only available to users with the RunAs privilege)    
sortby query sort fields. Supported fields are id, created, lastmodified and name. id "CREATED" or "ID" 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
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 Organisationss.
Response Headers
name description
Link contains links to the first, last, next and previous result pages

Example

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

Creates a new organisation.

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 CreateOrganisationRequest (JSON) registration information about the new organisation
Response Codes
code condition
201 if the organisation was created successfully
400
  • if not all required fields are provided (error code 400005) or
  • if a field was syntactically incorrect (error code 400007).
401 if the user could not be authenticated (error code 401001)
403 if the user is not allowed to create organisations (error code 403001)
409 if an organisation with the given name or login name exists already (error code 409001)
Response Body
media type data type description
application/json Organisation (JSON) the new organisation
Response Headers
name description
Location points to the created organisation. Only returned if the request was successful.

Example

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

                
{
  "login" : "dnb",
  "password" : "xasg!mk23cfw3e",
  "name" : "Deutsche Nationalbibliothek",
  "email" : "urn-group@example.org",
  "address" : {
    "street" : "Adickesallee 1",
    "postcode" : "60322",
    "city" : "Frankfurt am Main",
    "country" : "Germany"
  },
  "comment" : "This organisation is used for testing purposes only",
  "primaryContactSurname" : "Cantor",
  "primaryContactForename" : "Georg",
  "primaryContactEmail" : "g.cantor@example.org",
  "primaryContactPhone" : "+49 69 1525-0",
  "primaryContactFunction" : "Team Lead URN-Services",
  "primaryContactComment" : "Only in the office until for 1pm"
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: ...

                
{
  "self" : "http://example.org/organisations/id/1",
  "id" : "1",
  "login" : "dnb",
  "created" : "2017-03-02T15:23:16.123Z",
  "lastModified" : "2017-03-02T15:23:16.123Z",
  "name" : "Deutsche Nationalbibliothek",
  "email" : "urn-group@example.org",
  "address" : {
    "street" : "Adickesallee 1",
    "postcode" : "60322",
    "city" : "Frankfurt am Main",
    "country" : "Germany"
  },
  "comment" : "This organisation is used for testing purposes only",
  "primaryContactSurname" : "Cantor",
  "primaryContactForename" : "Georg",
  "primaryContactEmail" : "g.cantor@example.org",
  "primaryContactPhone" : "+49 69 1525-0",
  "primaryContactFunction" : "Team Lead URN-Services",
  "primaryContactComment" : "Only in the office until for 1pm",
  "contacts" : "http://example.org/organisation/id/1/contacts",
  "namespaces" : "http://example.org/organisation/id/1/namespaces"
}