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.

Example Library

An example library for common uses cases (Groovy and Python / curl) is available at: https://github.com/ER-FIZKarlsruhe/radar-api-demo

The examples include, e.g.:

  • Retrieve and renew OAuth tokens
  • View and create workspaces
  • Create a record with RADAR XML metadata
  • Upload individual files and archives
  • Check upload progress
  • Search content
  • Start and end a review
  • Validate metadata
  • Archive / publish a record

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

 MethodPathQueryReturn
ReadGET/users/{username} 200, 400, 401, 500
SearchGET/users

sort

offset

rows

query

200, 400

Schema

 Method   PathQuery   Return
CreatePOST/schemas/{contractid} 201, 400, 401, 403, 500
ReadGET/schemas/{contractid}/{key}/{version} 200, 401, 403, 404, 500
UpdatePUT/schemas/{contractid} 200, 400, 401, 403, 404, 500
DeleteDELETE/schemas/{contractid}/{key}/{version} 204, 401, 403, 404, 500
Read all versions of a SchemaGET/schemas/{contractid}/{key} 200, 401, 403, 404, 500
Read all schemas of a ContractGET/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

 MethodPathQueryReturn
CreatePOST/contracts 201, 400, 401, 403, 500
ReadGET/contracts/{id} 200, 401, 403, 404, 500
ChildrenGET/contracts/{id}/children

sort

offset

rows

200, 401, 403, 404, 500
UpdatePUT/contracts/{id} 200, 400, 401, 403, 404, 500
DeleteDELETE/contracts/{id} 200, 401, 403, 404, 500
Read AdministratorsGET/contracts/{id}/administrators 200, 401, 403, 404, 500
Change AdministratorsPOST/contracts/{id}/administrators 200, 401, 403, 404, 500
SearchGET/contracts

sort

offset

rows

query

200, 400
Get XML metadataGET/contracts/{id}/metadata 200, 401, 403, 404, 422, 500
Import XML metadataPOST/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

 MethodPathQueryReturn
CreatePOST/contracts/${contractId}/workspaces 201, 400, 401, 403, 500
ReadGET/workspaces/{id} 200, 401, 403, 404, 500
UpdatePUT/workspaces/{id} 200, 400, 401, 403, 404, 500
DeleteDELETE/workspaces/{id} 200, 401, 403, 404, 500
ChildrenGET/workspaces/{id}/children 200, 401, 403, 404, 500
Read CuratorsGET/workspaces/{id}/curators 200, 401, 403, 404, 500
Change CuratorsPOST/workspaces/{id}/curators 200, 401, 403, 404, 422, 500
Read Curators PreassignedGET/workspaces/{id}/curators/preassigned 200, 401, 403, 404, 500
Change Curators PreassignedPOST/workspaces/{id}/curators/preassigned 200, 401, 403, 404, 422, 500
Read SubcuratorsGET/workspaces/{id}/subcurators 200, 401, 403, 404, 500
Change SubcuratorsPOST/workspaces/{id}/subcurators 200, 401, 403, 404, 422, 500
Read Subcurators PreassignedGET/workspaces/{id}/subcurators/preassigned 200, 401, 403, 404, 500
Change Subcurators PreassignedPOST/workspaces/{id}/subcurators/preassigned 200, 401, 403, 404, 422, 500
SearchGET/workspaces

sort

offset

rows

query

facetValues[]

200, 400
FacetsGET/workspaces/facets

facetName

searchQuery

facetQuery

facetValues[]

rows

200, 400
Get XML metadataGET/workspaces/{id}/metadata 200, 401, 403, 404, 422, 500
Import XML metadataPOST/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

Uploading files to a 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.
  • If you want to upload via WebDAV, you must set the query parameter `webdav=true` when creating the dataset

 

QueryParamMethodPathQueryReturn
CreatePOST/workspaces/${workspaceId}/datasetswebdav=true201, 400, 401, 403, 500
ReadGET/datasets/{id} 200, 401, 403, 404, 500
UpdatePUT/datasets/{id} 200, 400, 401, 403, 404, 500
DeleteDELETE/datasets 200, 401, 403, 404, 500
DownloadGET/datasets/{id}/downloademail200, 401, 403, 404, 500
Can upload fileGET/datasets/{id}/canuploadfilename200, 401, 403, 404, 422, 500
SearchGET/datasets

sort

offset

rows

query

facetValues[]

200, 400
ChildrenGET/datasets/{id}/children/

sort

offset

rows

200, 401, 403, 500
FacetsGET/datasets/facets

facetName

searchQuery

facetQuery

facetValues[]

rows

200, 400
PublishPOST/datasets/{id}/publish 200, 401, 403, 404, 422, 500
ArchivePOST/datasets/{id}/archive 200, 401, 403, 404, 422, 500
ReviewPOST/datasets/{id}/startreview 200, 401, 403, 404, 422, 500
PendingPOST/datasets/{id}/endreview 200, 401, 403, 404, 422, 500
Retrieve DOI from datasetGET/datasets/{id}/doi 200, 401, 403, 404, 422, 500
Assign new DOI to datasetPOST/datasets/{id}/doi 200, 401, 403, 404, 422, 500
Get XML metadataGET/datasets/{id}/metadata 200, 401, 403, 404, 422, 500
Import XML metadataPOST/datasets/{id}/metadata 200, 401, 403, 404, 422, 500
Validate XML metadataGET/datasets/{id}/metadata/validate 200, 401, 403, 404, 500
Get metadata correctionGET/datasets/{id}/metadata-correction 200, 401, 403, 404, 500
Set metadata correctionPOST/datasets/{id}/metadata-correction 200, 401, 403, 404, 422, 500
Delete metadata correctionDELETE/datasets/{id}/metadata-correction 200, 401, 403, 404, 500
Release metadata correctionPOST/datasets/{id}/metadata-correction/release 200, 401, 403, 404, 500
Get total access and downloadsGET/datasets/{id}/statistics 200, 400
Import WebdavPOST/datasets/{id}/importWebdav 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.3"
         }
     },
   "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

 MethodPathQueryReturn
CreatePOST

/datasets/${datasetId}/folders

/folders/${folderId}/folders

 201, 400, 401, 403, 500
ReadGET/folders/{id} 200, 401, 403, 404, 500
UpdatePUT/folders/{id} 200, 400, 401, 403, 404, 500
DeleteDELETE/folders/{id} 200, 401, 403, 404, 500
Can upload fileGET/folders/{id}/canuploadfilename200, 401, 403, 404, 422, 500
ChildrenGET/folders/{id}/children

sort

offset

rows

200, 401, 403, 500
SearchGET/folders

sort

offset

rows

query

facetValues[]

200, 400
FacetsGET/folders/facets

facetName

searchQuery

facetQuery

facetValues[]

rows

200, 400
Import XML metadataPOST/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

 MethodPath Return
ReadGET/files/{id} 200, 401, 403, 404, 500
UpdatePUT/files/{id} 200, 400, 401, 403, 404, 500
DeleteDELETE/files/{id} 200, 401, 403, 404, 500
SearchGET/files

sort

offset

rows

query

facetValues[]

200, 400
FacetsGET/files/facets

facetName

searchQuery

facetQuery

facetValues[]

rows

200, 400
Import XML metadataPOST/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
   }
}