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.

_images/api_post_metadata_ok.svg

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:

_images/api_post_metadata_err.svg

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:

  1. File Announcement [application/json][POST]

  2. File Upload [multipart/form-data][POST]

  3. 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.

_images/api_post_files.svg

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 Request The request was malformed

  • HTTP Not Found (404) The URL or the request headers are invalid

  • HTTP 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”.

_images/api_put_files.svg

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 Request The 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 resource

  • HTTP Not Found (404) The URL is invalid

  • HTTP 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:

_images/api_post_submissions.svg

The following failures are possible:

  • HTTP Unauthorized (401) No valid authentication was provided

  • HTTP 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 returned

  • submittedBefore - only metadatasets with a submission date before the specified ISO datetime string will be returned

  • awaitingService - 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

  • 400 Bad Request

    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
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

  • 400 Bad Request

    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
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
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"
    }
    

  • 307 Temporary Redirect

    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"
    }
    

  • 400 Bad Request

    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.

  • 400 Bad Request

    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

  • 400 Bad Request

    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"
        }
    }
    

  • 400 Bad Request

    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.

  • 400 Bad Request

    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.

  • 400 Bad Request

    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.

  • 400 Bad Request

    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

  • 400 Bad Request

    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

  • 400 Bad Request

    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

  • 400 Bad Request

    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

  • 403 Forbidden

    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.

  • 400 Bad Request

    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.

  • 400 Bad Request

    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"
    }
    

  • 400 Bad Request

    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

  • 403 Forbidden

    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

  • 400 Bad Request

    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

  • 403 Forbidden

    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

  • 400 Bad Request

    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
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"
            }
        ]
    }
    

  • 400 Bad Request

    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

  • 400 Bad Request

    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.

  • 400 Bad Request

    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"
    }
    

  • 400 Bad Request

    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
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

  • 400 Bad Request

    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"
            }
        ]
    }
    

  • 400 Bad Request

    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"
            }
        ]
    }
    

  • 400 Bad Request

    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

  • 400 Bad Request

    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