RADAR API

Getting started with the RADAR API

Before you start

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

  1. Contact us for activating an OAuth ClientID. This client gives you permission to communicate with the RADAR backend authorization service.
  2. 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 Query 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

Schema

  Method    Path Query    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
   }
}