Using the REST API
Besides using the web interface or Python library, you may also access a DataMeta server by directly interacting with its API. On this page, you find the technical documentation of all RESTful API endpoints. In addition, in the following sections we will walk you through the details of API authentication, metadata and file upload and finalizing a submission.
Authentication to the API
Every request made against the API has to be accompanied with a secret that identifies you, i.e. links the request to your account on the DataMeta server. We refer to these secrets as API keys and you can obtain them from your “Account” tab in the DataMeta web interface. API keys are randomly generated strings of length 64 made of characters and digits.
To include the secret in your API request, you have to add the following request header:
Authorization: Bearer 7dywAFfI4DhuN4hp348FgfTjir6gWTw2p2KIca97VWA5uUH7CvY4U1xr7QRHrKpD
where 7dywAFfI4DhuN4hp348FgfTjir6gWTw2p2KIca97VWA5uUH7CvY4U1xr7QRHrKpD denotes the API key
obtained through the web interface.
API URL
The API of a DataMeta server is accessible at
https://{base_url}/api/{api_version}
To find out which API version is used by a DataMeta server, you may access the URL
https://{base_url}/api
which will respond with an HTTP Found (302) response returning the full length URL including
the API version in the Location response header.
Identifiers
All resources that are handled by the API come with at least one unique identifier, their UUID. In
addition, some resources may have a more human readable identifier, referred to as their site ID.
When a JSON response describes a resource, its IDs are typically annotated as follows in an
attribute called id:
{
"id": {
"uuid": "eb15fa40-af0a-46b7-a35f-0661851076fb",
"site": "CDF-51228765"
},
"otherAttribute": "value",
...
}
When another resource is referenced from within a resource, for example the user owning a file, the
attribute would typically be called userId and again contain an object with the attributes
id and site to refer to the two identifiers.
Only the id.uuid attribute is guaranteed to be present for all resources. When specifying a
resource in a request, the two identifier types are both recognized by the server and can be used
interchangeably.
Metadata Information
A description of the CoGDat metadata is provided under CoGDat Metadata as well as in the
submission interface when clicking the question mark icon on the submit page. The metadata
definitions can also be access programmatically by making a GET request against /metadata:
curl -X GET "https://data.cogdat.de/api/v1/metadata"
The response is a list of metadata definitions, each describing one metadatum with the corresponding constraints:
[
{
"id": {
"uuid": "c092aba6-b264-4632-be31-a6807e52ca81"
},
"name": "Lab-ID",
"isMandatory": true,
"order": 100,
"isFile": false,
"isSubmissionUnique": false,
"isSiteUnique": true,
"regexDescription": null,
"longDescription": "The sample ID as used by the submitting laboratory",
"example": "AB45",
"regExp": null,
"dateTimeFmt": null,
"serviceId": null
},
{
...
},
...
]
Note that the API response includes regular and service metadata. For regular metadata, the
serviceId attribute is set to NULL. For service metadata, the serviceId
attribute is an object holding the Identifiers of the corresponding Service.
Metadata Uploads
To upload metadata, a POST request is made against the /metadatasets endpoint. The JSON
request body contains a single metadataset. If the metadataset upload was successful, the server
responds with a HTTP OK (200) response and returns a JSON body which reflects the
metadataset that was just inserted. The actual metadata is contained in the records
attribute of the response, in addition the response contains information about the identifiers that
were assigned to the metadataset and the ownership of the metadataset. Note that the response also
contains an attribute named submissionId which is always null at this stage, as the
newly created metadataset has not yet been added to a submission.
The metadataset upload may fail for various reasons. If the request was made without proper
authentication, the DataMeta server will issue a HTTP Unauthorized (401) response. In
addition, the upload may fail for various verification related reasons, in which case the server
issues a HTTP Bad Request (400) annotated with a JSON body containing a list of the
verification errors that occurred:
In the example shown above, the metadataset upload failed validation, as there exists a field
constraint for the field ZIPCode, which states that the values have to be exactly three
digits.
File Uploads
In contrast to metadataset uploads, uploading a file cannot be done in a single API request. For a file upload, the following three requests have to be made:
File Announcement
[application/json][POST]File Upload
[multipart/form-data][POST]File Upload Confirmation
[application/json][PUT]
File Announcement
The first step in the file upload is to announce the file to the server. For that purpose, a POST
request is made against the /files endpoint, announcing the name and checksum of the file in
a JSON request body. A database record for the file will be created and returned to the client,
denoting the identifier, name and ownership of the file. Additionally, the attributes
urlToUpload, requestHeaders and expires provide information on how to upload
the actual file data: To upload the data, a multipart/form-data HTTP POST request has be be
made against the URL denoted in urlToUpload (see next section). The expiration of the upload
URL is denoted in the expires attribute.
The request may fail because of authentication issues, in which case a HTTP Unauthorized
(401) response is returned, or because the request was malformed, in which case a HTTP Bad
Request (400) response is returned.
File Upload
The response returned after the file announcement contains an upload URL and a set of request headers that are required when making the upload. The following cURL command would reflect the correct upload procedure for the file shown in the previous announcement example:
curl \
-X POST \
-H "Access-Token: LFEO1D2bjWfIJAQnTmnPaPLh9bAWYp0wAfRkI5yOWAPrzxsPZtmO6Dmw9t6FWsvk" \
-H "Content-Type: multipart/form-data" \
-F file=@ABC123_R1.fq.gz \
https://data.cogdat.de/api/v1/upload/eb15fa40-af0a-46b7-a35f-0661851076fb
If the upload was successful, the server responds with a HTTP No Content (204) response. The
following failures are possible:
HTTP Bad RequestThe request was malformedHTTP Not Found (404)The URL or the request headers are invalidHTTP Conflict (409)The upload for this file was already finalized (see next section)
⚠️ Note that the upload URL will not necessarily be a URL pointing to the DataMeta server, depending on the server configuration the URL may point to another storage server.
File Upload Confirmation
The file upload can in principle be repeated an arbitrary number of times and the corresponding storage will
be overwritten. To finalize the file transfer, a PUT request has to be made against the
/files endpoint to change the state of the file to “content uploaded”.
If the update was successful, the server will respond with a HTTP Ok (200) response and
return the updated file resource as a JSON body. The following failures are possible:
HTTP Bad RequestThe request was malformed. The error comes with a JSON response body containing a list of errors that occurred. The following errors specific to this endpoint are associated with this reponse: * The resource has been finalized already and can no longer be modified * No data was uploaded yet for this file.HTTP Unauthorzied (401)The requesting user is unauthorized to modify this resourceHTTP Not Found (404)The URL is invalidHTTP Conflict (409)The checksum of the uploaded data does not match the announced checksum
Submissions
Initially, all uploaded files and metadatasets are in a pending state which is private to the user. To finalize the upload, a submission is created, linking the metadatasets to the corresponding files. The submission also includes a final validation, in particular of any type of uniqueness constraints that may be defined for certain metadata fields.
To create a new submission, a POST request is made against the submissions endpoint. The
request body lists all metadatasets and files that are to be included in the submission by denoting
their IDs. Site IDs and UUIDs can be used interchangeably. Additionally, a label which annotates
the submission can be specified.
If the creation of the submission was successful, the server responds with a HTTP Ok (200)
response and reflects the created submission in the response body:
The following failures are possible:
HTTP Unauthorized (401)No valid authentication was providedHTTP Bad Request (400)The request was malformed or the provided submission failed validation. If a validation failure occurred, a list of failures is reported.
Querying Metadatasets
The GET endpoint metadatasets enables users to query metadatasets according to the
following search criteria:
submittedAfter- only metadatasets with a submission date after the specified ISO datetime string will be returnedsubmittedBefore- only metadatasets with a submission date before the specified ISO datetime string will be returnedawaitingService- only metadatasets for which the service corresponding to the specified service ID has not yet been executed will be returned.
When multiple criteria are specified, the criteria will be combined by logical AND.
Example request:
curl -X GET "https://data.cogdat.de/api/v0/metadatasets?awaitingService=CDP-54772300"
The response is a list of metadatasets. A detailed description of the response schema can be found below at GET /metadatasets.
Service Executions
Results of a service execution, i.e. missing service metadata for a metadataset is reported using
the POST endpoint /service-execution. The endpoint has two in-path parameters, the
first one being an identifier of the service and the second one being an identifier of the
metadataset.
In the following example, an ENA ID is reported for a metadataset:
curl -X POST "https://data.cogdat.de/api/v0/service-execution/CDP-58329011/CDM-36231117" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{"record":{"CoGDat-ENA-ID":"ABC-123"},"fileIds":[]}'
The endpoint is documented below under POST service-execution.
API Specification
In the following the technical specifications of every API endpoint are enlisted. Note that every DataMeta server also offers a Swagger based web UI to access the endpoint specifications, which may be more convenient to read and also offers the possibility to interactively try out the functionality of the API endpoints. For the CoGDat portal the Swagger based web UI is accessible at https://data.cogdat.de/api/.
- POST /keys
Create new API Key/Token
Create new API Key/Token
Example request:
POST /keys HTTP/1.1 Host: example.com Content-Type: application/json { "email": "string", "password": "string", "label": "string", "expires": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "userId": { "uuid": "string", "site": "string" }, "token": "string", "label": "string", "expires": "string" }
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- DELETE /keys/{id}
Delete ApiKey by label
Delete ApiKey by label.
- Parameters
id (string) – ID (not label) of Apikey
- Status Codes
200 OK – OK
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified key does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /rpc/whoami
[Not RESTful]: Returns information about the authenticated user
Returns the ids, name, groupAdmin, siteAdmin, email and groupName attributes for the logged in user. [Attention this endpoint is not RESTful, the result should not be cached.]
Example request:
GET /rpc/whoami HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "groupAdmin": true, "siteAdmin": true, "siteRead": true, "email": "string", "group": { "id": { "uuid": "string", "site": "string" }, "name": "string" } }
401 Unauthorized – Unauthorized
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /rpc/delete-files
Bulk-delete Staged Files
Bulk-delete Staged Files.
Example request:
POST /rpc/delete-files HTTP/1.1 Host: example.com Content-Type: application/json { "fileIds": [ "string" ] }
- Status Codes
204 No Content – Deletion successful
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – File not found
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /rpc/delete-metadatasets
Bulk-delete Staged MetaDataSets
Bulk-delete Staged MetaDataSets.
Example request:
POST /rpc/delete-metadatasets HTTP/1.1 Host: example.com Content-Type: application/json { "metadatasetIds": [ "string" ] }
- Status Codes
204 No Content – Deletion successful
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – File not found
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /rpc/get-file-url/{id}
[Not RESTful]: Redirects to a temporary, pre-signed HTTP-URL for downloading a file.
For the file with the given ID, this enpoint will redirect to a pre-signed HTTP URL for downloading the requested file. The pre-signed URL times out after a certain amount of time which can be configured with the “expires” query string. [Attention this endpoint is not RESTful, the result should not be cached.]
- Parameters
id (string) – ID of the file
- Query Parameters
expires (integer) – Minutes until the pre-signed URL will expire, defaults to 1
redirect (boolean) – If set to true, the endpoint will return a 307 response, otherwise a 200 response.
Example request:
GET /rpc/get-file-url/{id} HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "fileId": { "uuid": "string", "site": "string" }, "fileUrl": "string", "expires": "2022-09-21T11:46:32.817733", "checksum": "string" }
Redirecting to the pre-signed URL of the file
Example response:
HTTP/1.1 307 Temporary Redirect Content-Type: application/json { "fileId": { "uuid": "string", "site": "string" }, "fileUrl": "string", "expires": "2022-09-21T11:46:32.817733", "checksum": "string" }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified file does not exist.
500 Internal Server Error – Internal Server Error
- Response Headers
location – Location to redirect to
- GET /users/{id}/keys
All API keys for a user
Get a list of all API keys for a user. Please note that you cannot retrieve the tokens themselves because they are stored in a hashed format in our database as only the respective user is allowed to know them.
- Parameters
id (string) – ID of the User
Example request:
GET /users/{id}/keys HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "id": { "uuid": "string", "site": "string" }, "label": "string", "expires": "string", "hasExpired": true } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified user does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- PUT /users/{id}/password
Update a user’s password
Update a user’s password. The user ID can be specified either as a UUID or as a site ID.
- Parameters
id (string) – User ID, either as UUID or as site ID. ‘0’ for password reset token based access.
Example request:
PUT /users/{id}/password HTTP/1.1 Host: example.com Content-Type: application/json { "passwordChangeCredential": "string", "newPassword": "string" }
- Status Codes
204 No Content – Password update successful
401 Unauthorized – Unauthorized
403 Forbidden – The specified user does not exist or is not the same user as the authorized user.
404 Not Found – Password reset token not found
410 Gone – Password reset token expired
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /users/{id}
Get user information
Get information about a user.
- Parameters
id (string) – ID of the user
Example request:
GET /users/{id} HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "groupAdmin": true, "siteAdmin": true, "siteRead": true, "email": "string", "groupId": { "uuid": "string", "site": "string" } }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – Not found
500 Internal Server Error – Internal Server Error
- PUT /users/{id}
Update a user’s credentials and status
Update a user’s name, group, admin status and enabled status.
- Parameters
id (string) – User ID
Example request:
PUT /users/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "groupId": "string", "groupAdmin": true, "siteAdmin": true, "siteRead": true, "enabled": true }
- Status Codes
204 No Content – User update successful
401 Unauthorized – Unauthorized
403 Forbidden – This user does not have the rights to perform this action.
404 Not Found – The specified user does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /metadata
Get metadata definitions
Get the metadata definitions that are configured for this site.
Example request:
GET /metadata HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "id": { "uuid": "string", "site": "string" }, "name": "string", "regexDescription": "string", "longDescription": "string", "example": "string", "regExp": "string", "dateTimeFmt": "string", "isMandatory": true, "order": 1, "isFile": true, "isSubmissionUnique": true, "isSiteUnique": true, "serviceId": { "uuid": "string", "site": "string" } } ]
401 Unauthorized – Unauthorized
500 Internal Server Error – Internal Server Error
- POST /metadata
Create a New MetaDatum
Create a new MetaDatum. This is an administrative Endpoint that is not accessible for regular users.
Example request:
POST /metadata HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "regexDescription": "string", "longDescription": "string", "example": "string", "regExp": "string", "dateTimeFmt": "string", "isMandatory": true, "order": 1, "isFile": true, "isSubmissionUnique": true, "isSiteUnique": true, "serviceId": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "regexDescription": "string", "longDescription": "string", "example": "string", "regExp": "string", "dateTimeFmt": "string", "isMandatory": true, "order": 1, "isFile": true, "isSubmissionUnique": true, "isSiteUnique": true, "serviceId": { "uuid": "string", "site": "string" } }
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified Service does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- PUT /metadata/{id}
Update a MetaDatum
Update a MetaDatum. This is an administrative Endpoint that is not accessible for regular users.
- Parameters
id (string) – User ID
Example request:
PUT /metadata/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "regexDescription": "string", "longDescription": "string", "example": "string", "regExp": "string", "dateTimeFmt": "string", "isMandatory": true, "order": 1, "isFile": true, "isSubmissionUnique": true, "isSiteUnique": true, "serviceId": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "regexDescription": "string", "longDescription": "string", "example": "string", "regExp": "string", "dateTimeFmt": "string", "isMandatory": true, "order": 1, "isFile": true, "isSubmissionUnique": true, "isSiteUnique": true, "serviceId": { "uuid": "string", "site": "string" } }
401 Unauthorized – Unauthorized
403 Forbidden – This user does not have the rights to perform this action.
404 Not Found – The specified service does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /metadatasets
Create a New MetaDataSet
Create a new MetaDataSet
Example request:
POST /metadatasets HTTP/1.1 Host: example.com Content-Type: application/json { "record": {} }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "record": {}, "fileIds": {}, "serviceExecutions": {}, "id": { "uuid": "string", "site": "string" }, "submissionId": { "uuid": "string", "site": "string" }, "userId": { "uuid": "string", "site": "string" } }
401 Unauthorized – Unauthorized
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /metadatasets
Query metadatasets
Query all metadatasets
- Query Parameters
submittedAfter (string) – ISO datetime string specifying an exclusive lower bound for the submission date of the returned metadatasets.
submittedBefore (string) – ISO datetime string specifying an exclusive upper bound for the submission date of the returned metadatasets.
awaitingService (string) – Identifier for a service. Restricts the result to metadatsets for which the specified service has not been executed yet.
Example request:
GET /metadatasets HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "record": {}, "fileIds": {}, "serviceExecutions": {}, "id": { "uuid": "string", "site": "string" }, "submissionId": { "uuid": "string", "site": "string" }, "userId": { "uuid": "string", "site": "string" } } ]
401 Unauthorized – Unauthorized
404 Not Found – Not Found
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /metadatasets/{id}
Get Details for a MetaDataSet
Get details for a metadataset.
- Parameters
id (string) – ID of the MetaDataSet
Example request:
GET /metadatasets/{id} HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "record": {}, "fileIds": {}, "serviceExecutions": {}, "id": { "uuid": "string", "site": "string" }, "submissionId": { "uuid": "string", "site": "string" }, "userId": { "uuid": "string", "site": "string" } }
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
404 Not Found – The specified metadataset does not exist.
500 Internal Server Error – Internal Server Error
- DELETE /metadatasets/{id}
Delete Not-Submitted Metadataset
Delete File. Please note: This is only allowed if the metadataset has not been part of a Submission, yet.
- Parameters
id (string) – ID of the Metadataset
- Status Codes
204 No Content – Deletion successful
401 Unauthorized – Unauthorized
Either forbidden or the resource is not modifiable
Example response:
HTTP/1.1 403 Forbidden Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
404 Not Found – The specified metadataset does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /service-execution/{serviceId}/{metadatasetId}
Endpoint to store the result of a service execution for a single metadataset
This endpoint is used to report the result of a service execution in the form of metadatum key - value pairs for the service-related metadata and corresponding files if file metadata are involved.
- Parameters
serviceId (string) – ID of the service
metadatasetId (string) – ID of the metadataset
Example request:
POST /service-execution/{serviceId}/{metadatasetId} HTTP/1.1 Host: example.com Content-Type: application/json { "record": {}, "fileIds": [ "string" ] }
- Status Codes
200 OK –
Update successful
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "record": {}, "fileIds": {}, "serviceExecutions": {}, "id": { "uuid": "string", "site": "string" }, "submissionId": { "uuid": "string", "site": "string" }, "userId": { "uuid": "string", "site": "string" } }
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified metadataset or service does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /files
Create a New File
Creates a new empty file object. Attention: this endpoint does not take the file content for upload. Instead, it will respond with a presigned URL which you can use to upload (PUT) your file content.
Example request:
POST /files HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "checksum": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "urlToUpload": "string", "requestHeaders": {}, "userId": { "uuid": "string", "site": "string" }, "expires": "string" }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
500 Internal Server Error – Internal Server Error
- GET /files/{id}
Get Details for A File
Get details for a file.
- Parameters
id (string) – ID of the File
Example request:
GET /files/{id} HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "contentUploaded": true, "checksum": "string", "filesize": 1, "userId": { "uuid": "string", "site": "string" }, "expires": "string" }
401 Unauthorized – Unauthorized
Either forbidden or the resource is not modifiable
Example response:
HTTP/1.1 403 Forbidden Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
404 Not Found – File not found
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- PUT /files/{id}
Update File Details
Update details for a File. E.g. to indicate that the File content has been uploaded (set contentUploaded=true). Please note: this only works for Files that have not been submitted, yet. Other file attributes (checksum and name) can only be updated until contentUploaded has been set to ‘true’.
- Parameters
id (string) – ID of the File
Example request:
PUT /files/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "contentUploaded": true, "checksum": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "contentUploaded": true, "checksum": "string", "filesize": 1, "userId": { "uuid": "string", "site": "string" }, "expires": "string" }
401 Unauthorized – Unauthorized
Either forbidden or the resource is not modifiable
Example response:
HTTP/1.1 403 Forbidden Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
404 Not Found – File not found
409 Conflict – Mismatch between uploaded data checksum and announced checksum
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- DELETE /files/{id}
Delete Not-Submitted File
Delete File. Please note: This is only allowed if the File has not been part of a Submission, yet.
- Parameters
id (string) – ID of the File
- Status Codes
204 No Content – Deletion successful
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – File not found
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /submissions
Create a New Submission
Creates a new Submission. A submission consists of a list of metadatasets and a list of files.
Example request:
POST /submissions HTTP/1.1 Host: example.com Content-Type: application/json { "metadatasetIds": [ "string" ], "fileIds": [ "string" ], "label": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "label": "string", "metadatasetIds": [ { "uuid": "string", "site": "string" } ], "fileIds": [ { "uuid": "string", "site": "string" } ] }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
500 Internal Server Error – Internal Server Error
- POST /presubvalidation
Pre-validate a submission
Pre-validates a submission request without actually creating a submission. A submission request consists of a list of metadatasets and a list of files.
Example request:
POST /presubvalidation HTTP/1.1 Host: example.com Content-Type: application/json { "metadatasetIds": [ "string" ], "fileIds": [ "string" ], "label": "string" }
- Status Codes
204 No Content – OK
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
500 Internal Server Error – Internal Server Error
- GET /groups/{id}/submissions
Get A List of All Submissions of A Group.
Get a list of all submissions of a group.
- Parameters
id (string) – ID of the group
Example request:
GET /groups/{id}/submissions HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "id": { "uuid": "string", "site": "string" }, "label": "string", "metadatasetIds": [ { "uuid": "string", "site": "string" } ], "fileIds": [ { "uuid": "string", "site": "string" } ] } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified group does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /groups/{id}
Get group information
Get information about a group.
- Parameters
id (string) – ID of the group
Example request:
GET /groups/{id} HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string" }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – Not found
500 Internal Server Error – Internal Server Error
- PUT /groups/{id}
Change the name of a group.
Change the name of a group.
- Parameters
id (string) – ID of the group
Example request:
PUT /groups/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string" }
- Status Codes
204 No Content – No Content
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – The specified group does not exist.
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /appsettings
GET all AppSettings
GET all AppSettings. This is an administrative Endpoint that is not accessible for regular users.
Example request:
GET /appsettings HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "id": { "uuid": "string", "site": "string" }, "key": "string", "valueType": "string", "value": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- POST /services
Create a new service.
Create a new service.
Example request:
POST /services HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string" }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "userIds": [ { "uuid": "string", "site": "string" } ] }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
500 Internal Server Error – Internal Server Error
- GET /services
Get Services information
Get names and IDs for all services
Example request:
GET /services HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "id": { "uuid": "string", "site": "string" }, "name": "string", "userIds": [ { "uuid": "string", "site": "string" } ] } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
500 Internal Server Error – Internal Server Error
- PUT /services/{id}
Update a specific service.
Update the name and/or the users of this service. If the name, or the userIds are omitted, those will not be updated upon request. To remove all users, an empty array must be submitted for userIds.
- Parameters
id (string) – ID of the service
Example request:
PUT /services/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "userIds": [ "string" ] }
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": { "uuid": "string", "site": "string" }, "name": "string", "userIds": [ { "uuid": "string", "site": "string" } ] }
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – Service does not exist
500 Internal Server Error – Internal Server Error
- GET /server
Get DataMeta server information
Get information about the DataMeta server serving this API
Example request:
GET /server HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "apiVersion": "string", "datametaVersion": "string" }
500 Internal Server Error – Internal Server Error
- POST /registrations
Create a new user registration request
Create a new user registration request
Example request:
POST /registrations HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "email": "string", "org_select": "string", "org_create": "string", "org_new_name": "string", "check_user_agreement": true }
- Status Codes
204 No Content – New User Registration Request created
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error
- GET /registrationsettings
Get details for the registration view
Get all available groups and the user agreement for the registration view
Example request:
GET /registrationsettings HTTP/1.1 Host: example.com
- Status Codes
200 OK –
OK
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "userAgreement": "string", "groups": [ { "id": { "uuid": "string", "site": "string" }, "name": "string" } ] }
500 Internal Server Error – Internal Server Error
- PUT /appsettings/{id}
Update a specific appsetting. This is an administrative Endpoint that is not accessible for regular users.
Update a specific appsetting
- Parameters
id (string) – ID of the appsetting
Example request:
PUT /appsettings/{id} HTTP/1.1 Host: example.com Content-Type: application/json { "value": "string" }
- Status Codes
204 No Content – App Settings Updated
401 Unauthorized – Unauthorized
403 Forbidden – Forbidden
404 Not Found – Setting does not exist
Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json [ { "exception": "string", "error_code": "string", "message": "string", "entity": { "uuid": "string", "site": "string" }, "field": "string" } ]
500 Internal Server Error – Internal Server Error