Rest New API Documentation

Large files (project archives, data overlays, layer images) are not sent in a single request. They are uploaded in chunks: first the upload is initiated, then the chunks are sent one by one, and finally the upload is completed, which concatenates the chunks into a single file. The file identifier returned when initiating the upload is used in all following calls, and it is also the identifier passed to other endpoints that consume an uploaded file. An upload that is never completed expires after 24 hours and is removed. The endpoints are served from /new_api/files.

1. Initiate upload

Opens a new upload session for a file and returns its identifier, which must be used in all subsequent chunk, status, complete and cancel calls. The expected number of chunks may be declared here, but it is optional.

1.1. HTTP request

POST /minerva/new_api/files HTTP/1.1

1.2. Request Fields

Path Type Description

Path	Type	Description
`originalFileName`	`String`	original name of the file being uploaded
`totalChunks`	`Number`	expected total number of chunks (optional)

originalFileName

String

original name of the file being uploaded

totalChunks

Number

expected total number of chunks (optional)

1.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files' -X POST \
    -H 'Authorization: Bearer xxxxxxxx' \
    -d '{"originalFileName":"example.zip","totalChunks":3}' \
    -H 'Content-Type: application/json'

1.4. HTTP response

HTTP/1.1 201 Created

1.5. Response Fields

Path Type Description

Path	Type	Description
`id`	`Number`	upload session identifier
`originalFileName`	`String`	original file name provided when initiating the upload
`status`	`String`	upload status: IN_PROGRESS or COMPLETED
`totalChunks`	`Number`	total number of chunks expected (null if not specified)
`receivedChunks`	`Array`	list of chunk numbers that have already been uploaded

id

Number

upload session identifier

originalFileName

String

original file name provided when initiating the upload

status

String

upload status: IN_PROGRESS or COMPLETED

totalChunks

Number

total number of chunks expected (null if not specified)

receivedChunks

Array

list of chunk numbers that have already been uploaded

1.6. Sample Response

{
  "id" : 55,
  "originalFileName" : "example.zip",
  "status" : "IN_PROGRESS",
  "totalChunks" : 3,
  "receivedChunks" : [ ]
}

2. Upload chunk

Sends a single fragment of the file content as a raw binary body; this call is repeated for every chunk of the file. Chunks are numbered from 1 and can be sent in any order - they are stored separately and put together in that order only when the upload is completed.

2.1. HTTP request

PUT /minerva/new_api/files/59/chunk/1 HTTP/1.1

2.2. Path Parameters

Table 1. /minerva/new_api/files/{id}/chunk/{chunkNumber}
Parameter	Description
`id`	file identifier
`chunkNumber`	chunk number (1-based)

2.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/59/chunk/1' -X PUT \
    -H 'Authorization: Bearer xxxxxxxx' \
    -d 'binary chunk data' \
    -H 'Content-Type: application/octet-stream'

2.4. HTTP response

HTTP/1.1 200 OK

3. Get upload status

Reports which chunk numbers the server has already received, so that an interrupted upload can be resumed by sending only the missing ones.

3.1. HTTP request

GET /minerva/new_api/files/62/upload_status HTTP/1.1

3.2. Path Parameters

Table 2. /minerva/new_api/files/{id}/upload_status
Parameter	Description
`id`	file identifier

3.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/62/upload_status' -X GET \
    -H 'Authorization: Bearer xxxxxxxx'

3.4. HTTP response

HTTP/1.1 200 OK

3.5. Response Fields

Path Type Description

Path	Type	Description
`id`	`Number`	upload session identifier
`originalFileName`	`String`	original file name provided when initiating the upload
`status`	`String`	upload status: IN_PROGRESS or COMPLETED
`totalChunks`	`Number`	total number of chunks expected (null if not specified)
`receivedChunks`	`Array`	list of chunk numbers that have already been uploaded

id

Number

upload session identifier

originalFileName

String

original file name provided when initiating the upload

status

String

upload status: IN_PROGRESS or COMPLETED

totalChunks

Number

total number of chunks expected (null if not specified)

receivedChunks

Array

list of chunk numbers that have already been uploaded

3.6. Sample Response

{
  "id" : 62,
  "originalFileName" : "example.zip",
  "status" : "IN_PROGRESS",
  "totalChunks" : 2,
  "receivedChunks" : [ 1 ]
}

4. Complete upload

Closes the upload session: the received chunks are concatenated in order into the final file, the temporary chunks are discarded and the status changes to COMPLETED. After this call the file identifier can be used by other endpoints, for instance to create a project.

4.1. HTTP request

POST /minerva/new_api/files/57:complete HTTP/1.1

4.2. Path Parameters

Table 3. /minerva/new_api/files/{id}:complete
Parameter	Description
`id`	file identifier

4.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/57:complete' -X POST \
    -H 'Authorization: Bearer xxxxxxxx'

4.4. HTTP response

HTTP/1.1 200 OK

4.5. Response Fields

Path Type Description

Path	Type	Description
`id`	`Number`	upload session identifier
`originalFileName`	`String`	original file name provided when initiating the upload
`status`	`String`	upload status: IN_PROGRESS or COMPLETED
`totalChunks`	`Number`	total number of chunks expected (null if not specified)
`receivedChunks`	`Array`	list of chunk numbers that have already been uploaded

id

Number

upload session identifier

originalFileName

String

original file name provided when initiating the upload

status

String

upload status: IN_PROGRESS or COMPLETED

totalChunks

Number

total number of chunks expected (null if not specified)

receivedChunks

Array

list of chunk numbers that have already been uploaded

4.6. Sample Response

{
  "id" : 57,
  "originalFileName" : "example.zip",
  "status" : "COMPLETED",
  "totalChunks" : null,
  "receivedChunks" : [ ]
}

5. Cancel upload

Abandons an upload that has not been completed yet, removing the chunks uploaded so far together with the file entry. Available only for administrators.

5.1. HTTP request

DELETE /minerva/new_api/files/56 HTTP/1.1

5.2. Path Parameters

Table 4. /minerva/new_api/files/{id}
Parameter	Description
`id`	file identifier

5.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/56' -X DELETE \
    -H 'Authorization: Bearer xxxxxxxx'

5.4. HTTP response

HTTP/1.1 200 OK

6. Get file info

Returns metadata of an uploaded file - its name, size, owner and whether the upload finished - plus the orphan flag telling whether the file is still referenced by any project, overlay or layer glyph. Accessible to the owner of the file and to administrators.

6.1. HTTP request

GET /minerva/new_api/files/61 HTTP/1.1

6.2. Path Parameters

Table 5. /minerva/new_api/files/{id}
Parameter	Description
`id`	file identifier

6.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/61' -X GET \
    -H 'Authorization: Bearer xxxxxxxx'

6.4. HTTP response

HTTP/1.1 200 OK

6.5. Response Fields

Path Type Description

Path	Type	Description
`id`	`Number`	file identifier
`originalFileName`	`String`	name of the file as uploaded by the client
`length`	`Number`	file size in bytes
`status`	`String`	file status: IN_PROGRESS or COMPLETED
`ownerId`	`Number`	identifier of the user who owns the file (null if no owner)
`orphan`	`Boolean`	true if the file is not referenced by any project, overlay or layer glyph

id

Number

file identifier

originalFileName

String

name of the file as uploaded by the client

length

Number

file size in bytes

status

String

file status: IN_PROGRESS or COMPLETED

ownerId

Number

identifier of the user who owns the file (null if no owner)

orphan

Boolean

true if the file is not referenced by any project, overlay or layer glyph

6.6. Sample Response

{
  "id" : 61,
  "originalFileName" : "example.zip",
  "length" : 11,
  "status" : "COMPLETED",
  "ownerId" : 1,
  "orphan" : true
}

7. List files

List all uploaded files. Available only for administrators.

7.1. HTTP request

GET /minerva/new_api/files/?size=10&page=0 HTTP/1.1

7.2. Query Parameters

Parameter Description

Parameter	Description
`page`	index of the page to fetch, counted from 0; 0 by default
`size`	number of entries on a page; 20 by default, 10000 at most

page

index of the page to fetch, counted from 0; 0 by default

size

number of entries on a page; 20 by default, 10000 at most

7.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files/?size=10&page=0' -X GET \
    -H 'Authorization: Bearer xxxxxxxx'

7.4. HTTP response

HTTP/1.1 200 OK

7.5. Response Fields

Path Type Description

Path	Type	Description
`content`	`Array`	list of files on the page
`content[].id`	`Number`	file identifier
`content[].originalFileName`	`String`	name of the file as uploaded by the client
`content[].length`	`Number`	file size in bytes
`content[].status`	`String`	file status: IN_PROGRESS or COMPLETED
`content[].ownerId`	`Number`	identifier of the user who owns the file (null if no owner)
`content[].orphan`	`Boolean`	true if the file is not referenced by any project, overlay or layer glyph
`totalPages`	`Number`	total number of pages
`totalElements`	`Number`	total number of elements
`numberOfElements`	`Number`	number of elements on this page
`size`	`Number`	page size
`number`	`Number`	page number

content

Array

list of files on the page

content[].id

Number

file identifier

content[].originalFileName

String

name of the file as uploaded by the client

content[].length

Number

file size in bytes

content[].status

String

file status: IN_PROGRESS or COMPLETED

content[].ownerId

Number

identifier of the user who owns the file (null if no owner)

content[].orphan

Boolean

true if the file is not referenced by any project, overlay or layer glyph

totalPages

Number

total number of pages

totalElements

Number

total number of elements

numberOfElements

Number

number of elements on this page

size

Number

page size

number

Number

page number

7.6. Sample Response

{
  "content" : [ {
    "id" : 58,
    "originalFileName" : "git-download.zip",
    "length" : 13998,
    "status" : "IN_PROGRESS",
    "ownerId" : 1,
    "orphan" : true
  }, {
    "id" : 60,
    "originalFileName" : "example.zip",
    "length" : 11,
    "status" : "COMPLETED",
    "ownerId" : 1,
    "orphan" : true
  } ],
  "totalPages" : 1,
  "totalElements" : 2,
  "numberOfElements" : 2,
  "size" : 10,
  "number" : 0
}

8. Get zip archive of a git repository

Clones a git repository on the server side and returns its content as a zip archive, so that a project kept in a repository can be uploaded without downloading it manually first. Only the working tree of a single branch is packed - the git history is not included. The archive is returned as the body of the response (attachment; filename=git.zip); it is at the same time stored as an uploaded file of the calling user, so it can be passed to endpoints that consume an uploaded file. Available to administrators and curators.

8.1. HTTP request

POST /minerva/new_api/files:get_zip_from_git HTTP/1.1

8.2. Request Fields

Path Type Description

Path	Type	Description
`url`	`String`	url of the git repository to be packed into a zip file
`branch`	`String`	branch to be checked out (default branch of the repository by default)

url

String

url of the git repository to be packed into a zip file

branch

String

branch to be checked out (default branch of the repository by default)

8.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/files:get_zip_from_git' -X POST \
    -H 'Authorization: Bearer xxxxxxxx' \
    -d '{"url":"https://gitlab.com/uniluxembourg/lcsb/BioCore/minerva/test-upload.git","branch":null}' \
    -H 'Content-Type: application/json'

8.4. HTTP response

HTTP/1.1 200 OK

Rest New API Documentation - Files

1. Initiate upload

1.1. HTTP request

1.2. Request Fields

1.3. CURL sample

1.4. HTTP response

1.5. Response Fields

1.6. Sample Response

2. Upload chunk

2.1. HTTP request

2.2. Path Parameters

2.3. CURL sample

2.4. HTTP response

3. Get upload status

3.1. HTTP request

3.2. Path Parameters

3.3. CURL sample

3.4. HTTP response

3.5. Response Fields

3.6. Sample Response

4. Complete upload

4.1. HTTP request

4.2. Path Parameters

4.3. CURL sample

4.4. HTTP response

4.5. Response Fields

4.6. Sample Response

5. Cancel upload

5.1. HTTP request

5.2. Path Parameters

5.3. CURL sample

5.4. HTTP response

6. Get file info

6.1. HTTP request

6.2. Path Parameters

6.3. CURL sample

6.4. HTTP response

6.5. Response Fields

6.6. Sample Response

7. List files

7.1. HTTP request

7.2. Query Parameters

7.3. CURL sample

7.4. HTTP response

7.5. Response Fields

7.6. Sample Response

8. Get zip archive of a git repository

8.1. HTTP request

8.2. Request Fields

8.3. CURL sample

8.4. HTTP response