REST API#

Okay, so if you made it this far, you may also like to see the examples folder inside the storck repo. It’s full of examples of usage of the api using python and requests library. All of those examples are run as part of the testing suite for storck.

Access#

Authorization#

POST /api/auth#

Authorize user

Example request:

http

POST /api/auth HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST http://example.com/api/auth -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- http://example.com/api/auth --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST http://example.com/api/auth Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/auth', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

  {
      "token":"7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be",
      "user_id":1,
      "email":"",
      "username":"test_user"
  }

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Response JSON Object:

token (str) – authorisation token of the user
user_id (int) – id of the user
email (str) – email of the user
username (str) – username

Workspace#

Create workspace#

POST /api/workspace#

Creates workspace

Example request:

http

POST /api/workspace HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be
Content-Type: application/x-www-form-urlencoded

name=how+to+create+workspace

curl

curl -i -X POST http://example.com/api/workspace -H "Accept: */*" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be" --data-raw 'name=how+to+create+workspace'

wget

wget -S -O- http://example.com/api/workspace --header="Accept: */*" --header="Content-Type: application/x-www-form-urlencoded" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be" --post-data='name=how+to+create+workspace'

httpie

echo name=how+to+create+workspace | http POST http://example.com/api/workspace Accept:"*/*" Content-Type:"application/x-www-form-urlencoded" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/workspace', headers={'Accept': '*/*', 'Content-Type': 'application/x-www-form-urlencoded', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'}, data='name=how+to+create+workspace')

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

  {
  "data":{
      "id":2,
      "name":"how to create workspace",
      "users":[
          {
              "id":1,
              "username":"test_user"
          }
      ],
      "tokens":[
          {
              "id":2,
              "workspace_id":2,
              "token":"60d8b2c4-3202-4139-81e3-f58806c652d3",
              "name":"Default token"
          }
      ]
  }
  }

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Form Parameters:

name – name of the newly created workspace

Response JSON Object:

id (int) – id of workspace
name (str) – name of workspace
users (arr) – array of users using this workspace
tokens (arr) – workspace token associated with this workspace

List workspaces#

POST /api/workspaces#

Get list of workspaces

Example request:

http

POST /api/workspaces HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST http://example.com/api/workspaces -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- http://example.com/api/workspaces --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST http://example.com/api/workspaces Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/workspaces', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "data":{
      "id":1,
      "workspaces":[
          {
              "id":1,
              "name":"Main workspace",
              "users":[
              {
                  "id":1,
                  "username":"test_user"
              }
              ],
              "tokens":[
              {
                  "id":1,
                  "workspace_id":1,
                  "token":"73f19f87-f741-4f53-ae50-a9272dc87ea7",
                  "name":"Default token"
              }
              ]
          },
          {
              "id":2,
              "name":"how to create workspace",
              "users":[
              {
                  "id":1,
                  "username":"test_user"
              }
              ],
              "tokens":[
              {
                  "id":2,
                  "workspace_id":2,
                  "token":"60d8b2c4-3202-4139-81e3-f58806c652d3",
                  "name":"Default token"
              }
              ]
          }
      ]
}}

Request Headers:

Authorization – optional OAuth token to authenticate

Status Codes:

200 OK – no error

Response JSON Object:

id (int) – id of user
workspaces (arr) – list of the workspaces associated with this user, for details on the content of the list reference create workspace section

Files upload and download#

Upload#

POST /api/file#

File upload

Example request:

http

POST /api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7 HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be
Content-Type: multipart/form-data

(@This probablye should be changed to json)

curl

curl -i -X POST 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' -H "Accept: */*" -H "Content-Type: multipart/form-data" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be" --data-raw '(@This probablye should be changed to json)'

wget

wget -S -O- 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' --header="Accept: */*" --header="Content-Type: multipart/form-data" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be" --post-data='(@This probablye should be changed to json)'

httpie

echo '(@This probablye should be changed to json)' | http POST 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' Accept:"*/*" Content-Type:"multipart/form-data" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7', headers={'Accept': '*/*', 'Content-Type': 'multipart/form-data', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'}, data='(@This probablye should be changed to json)')

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 1,
  "duplicate": false,
  "previous_version": "None"
}

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (string) – Workspace token

Form Parameters:

path – file path to be stored in storck
metadata – metadata to be stored along the file
file – the file along it’s content

Response JSON Object:

id (int) – id of file
duplicate (bool) – True if file is duplicate of another file in storck
previous_version (int) – if previously a file existed under this path, then the id of the previous version of the file is returned

Download#

The best way is to get the files using file id’s:

GET /api/file#

File download by id

Example request:

http

POST /api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&id=1 HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&id=1' -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&id=1' --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST 'http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&id=1' Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/file?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&id=1', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

Hello World

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (string) – Workspace token
id (int) – file id

The other option is getting file by path, which will allways return the newest file under that path.

GET /api/file#

File download by path

Example request:

http

POST /api/file?path=..%2FexampleFile.txt&token=73f19f87-f741-4f53-ae50-a9272dc87ea7 HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST 'http://example.com/api/file?path=..%2FexampleFile.txt&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- 'http://example.com/api/file?path=..%2FexampleFile.txt&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST 'http://example.com/api/file?path=..%2FexampleFile.txt&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/file?path=..%2FexampleFile.txt&token=73f19f87-f741-4f53-ae50-a9272dc87ea7', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

Hello World

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (str) – Workspace token
path (str) – storage path

Browsing files#

File info#

GET /api/info#

File download

Example request:

http

POST info?id=1&token=73f19f87-f741-4f53-ae50-a9272dc87ea7 HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST 'http://example.cominfo?id=1&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- 'http://example.cominfo?id=1&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST 'http://example.cominfo?id=1&token=73f19f87-f741-4f53-ae50-a9272dc87ea7' Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.cominfo?id=1&token=73f19f87-f741-4f53-ae50-a9272dc87ea7', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

  {
  "file":{
      "id":1,
      "file":"exampleFile.txt",
      "hash":"3e25960a79dbc69b674cd4ec67a72c62",
      "workspace_id":1,
      "user_id":1,
      "previous_version_id":"None",
      "duplicate_of_id":"None",
      "date":"2022-03-11T10:19:44.674709Z",
      "stored_path":"../exampleFile.txt",
      "metadata":{
          "testproperty":"testvalue"
      },
      "meta_closed":"None",
      "hide":false
  }
  }

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (string) – Workspace token
id (int) – file id

Response JSON Object:

files (arr) – array of all of the files stored in workspace, with their details
id (int) – id of file
file (str) – uploaded filename
workspace_id (int) – the id of workspace
user_id (int) – the id of user who uploaded the file
previous_version_id (int) – the id of the previous version of the file
duplicate_of_id (int) – the id of the duplicate of the file
date (str) – the date of upload
stored_path (str) – the storage path
metadata (obj) – json containing the metadata
meta_closed (str) – close metadata
hide (bool) – if true this file should be hidden from viewing

Listing files#

GET /api/search#

Listing files

Example request:

http

POST /api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7 HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7' Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

  {
  "files":[
      {
          "id":1,
          "file":"exampleFile.txt",
          "hash":"3e25960a79dbc69b674cd4ec67a72c62",
          "workspace_id":1,
          "user_id":1,
          "previous_version_id":"None",
          "duplicate_of_id":"None",
          "date":"2022-03-11T10:19:44.674709Z",
          "stored_path":"../exampleFile.txt",
          "metadata":{
              "testproperty":"testvalue"
          },
          "meta_closed":"None",
          "hide":false
      }
  ]
  }

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (string) – Workspace token

Response JSON Object:

files (arr) – array of all of the files stored in workspace, with their details (description of the details can be found in file info)

Searching for files#

GET /api/search#

Searching for files using the metadata

Example request:

http

POST /api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&query_search=%7B%22metadata%22%3A+%7B%22testproperty%22%3A+%22testvalue%22%7D%7D HTTP/1.1
Host: example.com
Accept: */*
Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be

curl

curl -i -X POST 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&query_search=%7B%22metadata%22%3A+%7B%22testproperty%22%3A+%22testvalue%22%7D%7D' -H "Accept: */*" -H "Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

wget

wget -S -O- 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&query_search=%7B%22metadata%22%3A+%7B%22testproperty%22%3A+%22testvalue%22%7D%7D' --header="Accept: */*" --header="Authorization: Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

httpie

http POST 'http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&query_search=%7B%22metadata%22%3A+%7B%22testproperty%22%3A+%22testvalue%22%7D%7D' Accept:"*/*" Authorization:"Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be"

python-requests

requests.post('http://example.com/api/search?token=73f19f87-f741-4f53-ae50-a9272dc87ea7&query_search=%7B%22metadata%22%3A+%7B%22testproperty%22%3A+%22testvalue%22%7D%7D', headers={'Accept': '*/*', 'Authorization': 'Token 7c817d0d8f0e2b719a9df798fbdefe75cf5ba4be'})

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

  {
  "files":[
      {
          "id":1,
          "file":"exampleFile.txt",
          "hash":"3e25960a79dbc69b674cd4ec67a72c62",
          "workspace_id":1,
          "user_id":1,
          "previous_version_id":"None",
          "duplicate_of_id":"None",
          "date":"2022-03-11T10:19:44.674709Z",
          "stored_path":"../exampleFile.txt",
          "metadata":{
              "testproperty":"testvalue"
          },
          "meta_closed":"None",
          "hide":false
      }
  ]
  }

Request Headers:

Authorization – OAuth token to authenticate

Status Codes:

200 OK – no error

Query Parameters:

token (string) – Workspace token
metadata (string) – A string containing json used to search through metadata (see here)

Response JSON Object:

files (arr) – array of all of the files stored in workspace, with their details (description of the details can be found in file info)