RADAR API

Erste Schritte zur Nutzung des RADAR API

Before you start
Target Systems
Security
Endpoints

Before you start

Before you start to use (or test) our RADAR API please:

Contact us for activating an OAuth ClientID. This client gives you permission to communicate with the RADAR backend authorization service.
In case you use RADAR with Shibboleth accounts: Please take note, that no Shibboleth account can be used for this API user, but only a user who has registered via the local RADAR database with ID / PW. Thus please create a new RADAR API user that is used to retrieve the OAuth token with its credentials.

An Example library for common uses cases is available at: https://dev.fiz-karlsruhe.de/stash/projects/RAD/repos/radar-api-demo/browse

Target Systems

The following basic URLs are to be used for the API calls*:

Development: https://test.radar-service.eu/radar/api/

Production: https://www.radar-service.eu/radar/api/

*not to be called up via the browser

Security

oAuth

Most of the endpoints requires an authenticated escidoc user to perform the action. In the RADAR all authentication is done via Oauth.

An API-Client has to send a valid Oauth Token in the request header to gain access to specific endpoints.

oAuth header:

Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Endpoints

oAuth Tokens

	Method	Path	Return
Read	POST	/tokens	200, 400, 401, 500
Delete	DELETE	/tokens	204, 400, 500
Read	POST	/tokens/refresh	200, 400, 401, 500

POST body for retrieving oauth tokens:

{"clientId":"myClientId", "clientSecret":"myClientSecret", "redirectUrl" : \"myRedirectUrl", "userName":"myUserName", "userPassword":"myPassword"}

POST body for refresh an oauth token:

{"clientId":"myClientId", "clientSecret":"myClientSecret", "refreshToken":"0b79bab50daca910b000d4f1a2b675d604257e42"}

User

	Method	Path	Query	Return
Read	GET	/users/{username}		200, 400, 401, 500
Search	GET	/users	sort offset rows query	200, 400

Method

Path

Query

Return

Read

GET

/users/{username}

200, 400, 401, 500

GET

/users

sort

offset

rows

query

200, 400

Schema

	Method	Path	Return
Create	POST	/schemas/{contractid}	201, 400, 401, 403, 500
Read	GET	/schemas/{contractid}/{key}/{version}	200, 401, 403, 404, 500
Update	PUT	/schemas/{contractid}	200, 400, 401, 403, 404, 500
Delete	DELETE	/schemas/{contractid}/{key}/{version}	204, 401, 403, 404, 500
Read all versions of a Schema	GET	/schemas/{contractid}/{key}	200, 401, 403, 404, 500
Read all schemas of a Contract	GET	/schemas/{contractid}	200, 401, 403, 404, 500

Body example for POST/PUT schema creation/update:

Example:

{
    "name": "SCHEMA_NAME",
    "contractId": "CONTRACT_ID",
    "key": "SCHEMA_KEY",
    "version": "SCHEMA_VERSION",
    "xsd": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<xs:schema xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" elementFormDefault=\"qualified\" attributeFormDefault=\"unqualified\">...\n</xs:schema>\n",
    "xsdName": "XSD_NAME",
    "xsdFileName": "XSD_FILENAME.xsd",
    "xsdUTCCreated": "2022-09-12T15:30:18.062909Z",
    "xslt": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" version=\"1.0\">...\n</xsl:stylesheet>\n",
    "xsltName": "XSLT_NAME",
    "xsltFileName": "XSLT_FILENAME.xslt",
    "xsltUTCCreated": "2022-09-12T15:30:18.062909Z"
}

Contract

	Method	Path	Query	Return
Create	POST	/contracts		201, 400, 401, 403, 500
Read	GET	/contracts/{id}		200, 401, 403, 404, 500
Update	PUT	/contracts/{id}		200, 400, 401, 403, 404, 500
Delete	DELETE	/contracts/{id}		200, 401, 403, 404, 500
Read Administrators	GET	/contracts/{id}/administrators		200, 401, 403, 404, 500
Change Administrators	POST	/contracts/{id}/administrators		200, 401, 403, 404, 500
Search	GET	/contracts	sort offset rows query	200, 400
Get XML metadata	GET	/contracts/{id}/metadata		200, 401, 403, 404, 422, 500
Import XML metadata	POST	/contracts/{id}/metadata		200, 401, 403, 404, 422, 500

POST body for creating a new contract:

Example:

{
   "id":null,
   "parentId":null,
   "createdDate":null,
   "lastModifiedDate":null,
   "descriptiveMetadata":{
      "title":"Test contract",
      "description":"This is the test contract"
   },
   "technicalMetadata":{
      "diskQuota":5000,
      "archiveQuota":10000,
      "categories":{
         "category":[
            {
               "title":"Institutions",
               "value":[
                  {
                     "value":"FIZ",
                     "id":"1453127511216"
                  },
                  {
                     "value":"SCC",
                     "id":"1453127511221"
                  },
                  {
                     "value":"IMK",
                     "id":"1453127511221"
                  }
               ],
               "id":"1453127511216"
            }
         ]
      }
   }
}

POST body for changing contract administrators:

["username1", "username1"]

Workspace

	Method	Path	Query	Return
Create	POST	/contracts/${contractId}/workspaces		201, 400, 401, 403, 500
Read	GET	/workspaces/{id}		200, 401, 403, 404, 500
Update	PUT	/workspaces/{id}		200, 400, 401, 403, 404, 500
Delete	DELETE	/workspaces/{id}		200, 401, 403, 404, 500
Read Curators	GET	/workspaces/{id}/curators		200, 401, 403, 404, 500
Change Curators	POST	/workspaces/{id}/curators		200, 401, 403, 404, 422, 500
Read Curators Preassigned	GET	/workspaces/{id}/curators/preassigned		200, 401, 403, 404, 500
Change Curators Preassigned	POST	/workspaces/{id}/curators/preassigned		200, 401, 403, 404, 422, 500
Read Subcurators	GET	/workspaces/{id}/subcurators		200, 401, 403, 404, 500
Change Subcurators	POST	/workspaces/{id}/subcurators		200, 401, 403, 404, 422, 500
Read Subcurators Preassigned	GET	/workspaces/{id}/subcurators/preassigned		200, 401, 403, 404, 500
Change Subcurators Preassigned	POST	/workspaces/{id}/subcurators/preassigned		200, 401, 403, 404, 422, 500
Search	GET	/workspaces	sort offset rows query facetValues[]	200, 400
Facets	GET	/workspaces/facets	facetName searchQuery facetQuery facetValues[] rows	200, 400
Get XML metadata	GET	/workspaces/{id}/metadata		200, 401, 403, 404, 422, 500
Import XML metadata	POST	/workspaces/{id}/metadata		200, 401, 403, 404, 422, 500

POST body for creating a new workspace:

Examples:

{
   "id":null,
   "parentId":"tSnyWSTKrtvieNpv",
   "createdDate":null,
   "lastModifiedDate":null,
   "datasetIds":null,
   "descriptiveMetadata":{
      "title":"Workspace Foo",
      "description":"to be used only by Alice and Bob"
   },
   "technicalMetadata":{
      "defaultDatasetRetentionPeriod":42,
      "defaultDatasetResponsibleEmail":"alice_and_bob [at] foo.bar (alice_and_bob[at]foo[dot]bar)",
      "categoryAssignments":{
         "categoryAssignment":[
            "JHJHASD,LKJKJASD",
            "KJHKJH,IJOIJASD3"
         ]
      }
   }
}

POST body for changing curators / subcurators:

["username1", "username1"]

POST body for changing curators/subcurators preassignment:

["user [at] institutaion.edu (user[at]institutaion[dot]edu)", "foo [at] bar.de (foo[at]bar[dot]de)"]

Dataset

In the JSON file of the dataset there is an uploadURL and an ingestURL.

The /ingest endpoint can only be used for EMPTY datasets. Files in the formats zip/tar/tar.gz/tar.bz are extracted during ingest.
The /upload endpoint can be used to upload any single files. If files in the formats zip/tar/tar.gz/tar.bz are uploaded, these archives will then NOT be extracted.

	Method	Path	Query	Return
Create	POST	/workspaces/${workspaceId}/datasets		201, 400, 401, 403, 500
Read	GET	/datasets/{id}		200, 401, 403, 404, 500
Update	PUT	/datasets/{id}		200, 400, 401, 403, 404, 500
Delete	DELETE	/datasets		200, 401, 403, 404, 500
Download	GET	/datasets/{id}/download	email	200, 401, 403, 404, 500
Can upload file	GET	/datasets/{id}/canupload	filename	200, 401, 403, 404, 422, 500
Search	GET	/datasets	sort offset rows query facetValues[]	200, 400
Children	GET	/datasets/{id}/children/	sort offset rows	200, 401, 403, 500
Facets	GET	/datasets/facets	facetName searchQuery facetQuery facetValues[] rows	200, 400
Publish	POST	/datasets/{id}/publish		200, 401, 403, 404, 422, 500
Archive	POST	/datasets/{id}/archive		200, 401, 403, 404, 422, 500
Review	POST	/datasets/{id}/startreview		200, 401, 403, 404, 422, 500
Pending	POST	/datasets/{id}/endreview		200, 401, 403, 404, 422, 500
Retrieve DOI from dataset	GET	/datasets/{id}/doi		200, 401, 403, 404, 422, 500
Assign new DOI to dataset	POST	/datasets/{id}/doi		200, 401, 403, 404, 422, 500
Get XML metadata	GET	/datasets/{id}/metadata		200, 401, 403, 404, 422, 500
Import XML metadata	POST	/datasets/{id}/metadata		200, 401, 403, 404, 422, 500
Validate XML metadata	GET	/datasets/{id}/metadata/validate		200, 401, 403, 404, 500
Get metadata correction	GET	/datasets/{id}/metadata-correction		200, 401, 403, 404, 500
Set metadata correction	POST	/datasets/{id}/metadata-correction		200, 401, 403, 404, 422, 500
Delete metadata correction	DELETE	/datasets/{id}/metadata-correction		200, 401, 403, 404, 500
Release metadata correction	POST	/datasets/{id}/metadata-correction/release		200, 401, 403, 404, 500

POST body for creating a new dataset:

Examples:

{
   "id":null,
   "parentId":"oCnmQAQTPXBomRIm",
   "createdDate":null,
   "lastModifiedDate":null,
   "hasChildren":false,
   "state":"PENDING",
   "uploadUrl":null,
   "technicalMetadata":{
      "retentionPeriod":25,
      "archiveDate":1453118839734,
      "publishDate":1453118839739,
      "responsibleEmail":"alice [at] bob.de (alice[at]bob[dot]de)",
      "publicationBacklink":"http://alice-bob.de/publication",
      "embargoEndingDate":1453982839735,
      "numberOfPendingNotificationMailsSent":0,
      "categoryAssignments":null,
         "schema":{
             "key":"RDDM",
                 "version":"9.1"
     }
   },
   "descriptiveMetadata":{
      "identifier":null,
      "alternateIdentifiers":null,
      "relatedIdentifiers":null,
      "creators":{
         "creator":[
            {
               "creatorName":"Max Mustermann",
               "creatorAffiliation":[
                  "Scientist"
               ]
            },
            {
               "creatorName":"Maike Maler",
               "creatorAffiliation":[
                  "Scientist"
               ]
            }
         ]
      },
      "contributors":null,
      "title":"Dataset title.",
      "additionalTitles":null,
      "descriptions":null,
      "keywords":null,
      "publishers":null,
      "productionYear":null,
      "publicationYear":null,
      "language":null,
      "subjectAreas":null,
      "resource":null,
      "geoLocations":null,
      "dataSources":null,
      "software":null,
      "processing":null,
      "rights":null,
      "rightsHolders":null,
      "relatedInformations":null
   }
}

Folder

	Method	Path	Query	Return
Create	POST	/datasets/${datasetId}/folders /folders/${folderId}/folders		201, 400, 401, 403, 500
Read	GET	/folders/{id}		200, 401, 403, 404, 500
Update	PUT	/folders/{id}		200, 400, 401, 403, 404, 500
Delete	DELETE	/folders/{id}		200, 401, 403, 404, 500
Can upload file	GET	/folders/{id}/canupload	filename	200, 401, 403, 404, 422, 500
Children	GET	/folders/{id}/children	sort offset rows	200, 401, 403, 500
Search	GET	/folders	sort offset rows query facetValues[]	200, 400
Facets	GET	/folders/facets	facetName searchQuery facetQuery facetValues[] rows	200, 400
Import XML metadata	POST	/folders/{id}/metadata		200, 401, 403, 404, 422, 500

POST body for creating a new folder:

Examples:

{
   "id":null,
   "parentId":"kVxkjkgGbiiZWJPp",
   "createdDate":null,
   "lastModifiedDate":null,
   "folders":null,
   "files":null,
   "descriptiveMetadata":{
      "identifier":null,
      "alternateIdentifiers":null,
      "relatedIdentifiers":null,
      "creators":{
         "creator":[
            {
               "creatorName":"Max Mustermann",
               "creatorAffiliation":[
                  "Scientist"
               ]
            },
            {
               "creatorName":"Maike Maler",
               "creatorAffiliation":[
                  "Scientist"
               ]
            }
         ]
      },
      "contributors":null,
      "title":"Folder Foo.",
      "additionalTitles":null,
      "descriptions":null,
      "keywords":null,
      "publishers":null,
      "productionYear":null,
      "publicationYear":null,
      "language":null,
      "subjectAreas":null,
      "resource":null,
      "geoLocations":null,
      "dataSources":null,
      "software":null,
      "processing":null,
      "rights":null,
      "rightsHolders":null,
      "relatedInformations":null
   }
}

File

	Method	Path		Return
Read	GET	/files/{id}		200, 401, 403, 404, 500
Update	PUT	/files/{id}		200, 400, 401, 403, 404, 500
Delete	DELETE	/files/{id}		200, 401, 403, 404, 500
Search	GET	/files	sort offset rows query facetValues[]	200, 400
Facets	GET	/files/facets	facetName searchQuery facetQuery facetValues[] rows	200, 400
Import XML metadata	POST	/files/{id}/metadata		200, 401, 403, 404, 422, 500

POST body for updating a file:

Examples:

{
   "id":"jhalksjdhfsadiu",
   "parentId":"dmCANFLLDgRhOYqb",
   "createdDate":null,
   "lastModifiedDate":null,
   "fileName":null,
   "binaryUrl":null,
   "descriptiveMetadata":{
      "identifier":null,
      "alternateIdentifiers":null,
      "relatedIdentifiers":null,
      "creators":{
         "creator":[
            {
               "creatorName":"Max Mustermann",
               "creatorAffiliation":[
                  "Scientist"
               ]
            },
            {
               "creatorName":"Maike Maler",
               "creatorAffiliation":[
                  "Scientist"
               ]
            }
         ]
      },
      "contributors":null,
      "title":"File bar.",
      "additionalTitles":null,
      "descriptions":null,
      "keywords":null,
      "publishers":null,
      "productionYear":null,
      "publicationYear":null,
      "language":null,
      "subjectAreas":null,
      "resource":null,
      "geoLocations":null,
      "dataSources":null,
      "software":null,
      "processing":null,
      "rights":null,
      "rightsHolders":null,
      "relatedInformations":null
   }
}