api.md

API

(JSON-in) All methods pass their argument in a json hash in the HTTP request body.
(JSON-out) All methods return a json hash in the HTTP response body.
GET is used for queries.
POST is used for modifiers.
Paths are not REST-ful.

Group API

POST group_create(manifest)

Creates a new group from the given manifest and returns its id.
See group_manifest below for a manifest overview.
See here for more detailed manifest information.

parameters
- manifest:Hash created by creator from languages-start-points and exercises-start-points or custom-start-points.
returns
- the id of the created group.

example

$ curl \
  --data '{"manifest":...}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/group_create | jq .

{
  "group_create":  "dFg8Us"
}

GET group_manifest(id)

Gets the manifest used to create the group with the given id.

parameters
- id:String. The group id.
returns
- the manifest of the group with the given id.

example

$ curl \
  --data '{"id":"dFg8Us"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/group_manifest | jq .

{
  "group_manifest": {
    "display_name": "Bash, bats",
    "image_name": "cyberdojofoundation/bash_bats:53d0c9c",
    "filename_extension": [
      ".sh"
    ],
    "tab_size": 4,
    "visible_files": {
      "test_hiker.sh": { "content": "..." },
      "bats_help.txt": { "content": "..." },
      "hiker.sh": { "content": "..." },
      "cyber-dojo.sh": { "content": "..." },
      "readme.txt": { "content": "..." }
    },
    "exercise": "LCD Digits",
    "version": 1,
    "created": [2020,10,19,12,51,32,991192],
    "id": "REf1t8",
    "highlight_filenames": [],
    "max_seconds": 10,
    "progress_regexs": []
  }
}

GET group_exists?(id)

Determines if a group with the given id exists.

parameters
- id:String. The group id.
returns
- true if a group with the given id exists, otherwise false.

example

$ curl \
  --data '{"id":"dFg8Us"}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/group_exists? | jq .

{
  "group_exists?": true
}

POST group_join(id)

Creates a new kata in the group with the given id and returns the kata's id.

parameters
- id:String. The group id.
returns
- the id of the created kata, or null if the group is already full.

example

$ curl \
  --data '{"id":"dFg8Us"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/group_join | jq .

{
  "group_join": "a8gVRN"
}

GET group_joined(id)

Returns the kata-id and kata-events-summary keyed against the kata's avatar-index (0-63) for the katas that have joined a group.

parameters
- id:String. The group's id or the id of any kata in the group.
returns
- a Hash.

example

$ curl \
  --data '{"id":"dFg8Us"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/group_joined | jq .

{
  "group_joined": {
    "7": {
      "id": "a8gVRN",
      "events": [...]
    },
    "29": {
      "id": "gUNjUV",
      "events": [...]
    },
    ...
   }
}

POST group_fork(id,index)

Creates a new group whose starting files are a copy of the files in the kata with the given id at the given index. The new group is not a fork in the git sense; that is, it is not a 'deep' copy, the history of commits (one per test event) that exist in the kata being forked are not copied.

parameters
- id:String. The id of the kata being forked.
- index:int. The event index to fork from.
returns
- the id of the created group.

example

$ curl \
  --data '{"id":"dFg8Us", "index":23}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/group_fork | jq .

{
  "group_fork": "a8gVRN"
}

Kata API

POST kata_create(manifest)

Creates a new kata from the given manifest and returns its id.
See kata_manifest below for a manifest overview.
See here for more detailed manifest information.

parameters
- manifest:Hash created by creator from languages-start-points and exercises-start-points (or custom-start-points).
returns
- the id of the created kata.

example

$ curl \
  --data '{"manifest":...}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_create | jq .

{
  "kata_create":  "dFg8Us"
}

GET kata_manifest(id)

Gets the manifest used to create the kata exercise with the given id.

parameters
- id:String. The kata id.
returns
- the manifest of the kata with the given id.

example

$ curl \
  --data '{"id":"4ScKVJ"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/kata_manifest | jq .

{
  "kata_manifest": {
    "display_name": "Bash, bats",
    "image_name": "cyberdojofoundation/bash_bats:53d0c9c",
    "filename_extension": [ ".sh" ],
    "tab_size": 4,
    "visible_files": {
      "test_hiker.sh": { "content": "..." },
      "bats_help.txt": { "content": "..." },
      "hiker.sh": { "content": "..." },
      "cyber-dojo.sh": { "content": "..." },
      "readme.txt": { "content": "..." }
    },
    "exercise": "LCD Digits",
    "version": 1,
    "created": [2020,10,19,12,52,46,396907],
    "group_id": "REf1t8",
    "group_index": 44,
    "id": "4ScKVJ",
    "highlight_filenames": [],
    "max_seconds": 10,
    "progress_regexs": []
  }
}

GET kata_exists?(id)

Determines if a kata exercise with the given id exists.

parameters
- id:String. The kata id.
returns
- true if a kata with the given id exists, otherwise false.

example

$ curl \
  --data '{"id":"4ScKVJ"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/kata_exists? | jq .

{
  "kata_exists?": false
}

GET kata_events(id)

Gets the summary of all current events for the kata with the given id.

parameters
- id:String. The kata id.
returns
- an Array holding the events summary of the kata with the given id.

example

$ curl \
  --data '{"id":"4ScKVJ"}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/kata_events | jq .

{
  "kata_events": [
    { "index": 0,
       "time": [2020,10,19,12,52,46,396907],
       "event": "created"
    },
    { "time": [2020,10,19,12,52,54,772809],
      "duration": 0.491393,
      "colour": "red",
      "predicted": "none",
      "index": 1
    },
    { "time": [2020,10,19,12,52,58,547002],
      "duration": 0.426736,
      "colour": "amber",
      "predicted": "none",
      "index": 2
    },
    { "time": [2020,10,19,12,53,3,256202],
      "duration": 0.438522,
      "colour": "green",
      "predicted": "none",
      "index": 3
    }
  ]
}

GET kata_event(id,index)

Gets the full details for the kata event whose kata has the given id whose event has the given index.

parameters
- id:String. The kata id.
- index:int. Negative values count backwards, -1 is the last index.
returns
- the event with the given id and index.

example

$ curl \
  --data '{"id":"4ScKVJ","index":2}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/kata_event | jq .

{
   "kata_event": {
     "files": {
       "test_hiker.sh": { "content": "..." },
       "bats_help.txt": { "content": "..." },
       "hiker.sh": { "content": "..." },
       "cyber-dojo.sh": { "content": "..." },
       "readme.txt": { "content": "..." }
     },
     "stdout": {
       "content": "...",
       "truncated": false
     },
     "stderr": {
       "content": "...",
       "truncated": false
     },
     "status": "1",
     "time": [2020,10,19,12,52,58,547002],
     "duration": 0.426736,
     "colour": "amber",
     "predicted": "none",
     "index": 2
   }
 }

GET katas_events(ids,indexes)

Gets the full details for the kata events with the given ids and indexes. A Batch-Method for kata_event(id,index).

parameters
- ids:Array[String]. The kata ids.
- index:Array[int]. The corresponding event indexes.
returns
- the events with the given ids and indexes.

example

$ curl \
  --data '{"ids":["4ScKVJ","De87Aa"],"indexes":[23,45]}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/katas_events | jq .

{
   "katas_events": {
     "4ScKVJ": {
       "23": {
         "files": { ... },
         "stdout": { ... }  
         ...
       }
     },
     "De87Aa": {
       "45": {
         "files": { ... },
         "stdout": { ... }  
         ...
       }
     }
   }
 }

GET kata_download(id)

Returns a gzipped tar archive of the kata's git repository, base64-encoded.

parameters
- id:String. The kata id.
returns
- an Array of two elements: the suggested filename (String) and the base64-encoded tgz content (String).

example

$ curl \
  --data '{"id":"4ScKVJ"}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/kata_download | jq .

{
  "kata_download": [
    "cyber-dojo-2026-4-6-4ScKVJ.tgz",
    "H4sIAAAAAAAAA+..."
  ]
}

POST kata_file_create(id,index,files,filename)

Records a new empty file being created in the browser. If any existing file has been edited since the last save, that edit is recorded first as a file_edit event.

parameters
- id:String. The kata id.
- index:int. The next event index.
- files:Hash. The current files (the new filename is not yet present).
- filename:String. The name of the file being created.
returns
- the event index to use for the next call.

example

$ curl \
  --data '{"id":"4ScKVJ","index":4,"files":{...},"filename":"utils.sh"}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_file_create | jq .

{
  "kata_file_create": 5
}

POST kata_file_delete(id,index,files,filename)

Records a file being deleted in the browser. If any existing file has been edited since the last save, that edit is recorded first as a file_edit event.

parameters
- id:String. The kata id.
- index:int. The next event index.
- files:Hash. The current files (the filename to delete is still present).
- filename:String. The name of the file being deleted.
returns
- the event index to use for the next call.

example

$ curl \
  --data '{"id":"4ScKVJ","index":5,"files":{...},"filename":"utils.sh"}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_file_delete | jq .

{
  "kata_file_delete": 6
}

POST kata_file_rename(id,index,files,old_filename,new_filename)

Records a file being renamed in the browser. If any existing file has been edited since the last save, that edit is recorded first as a file_edit event.

parameters
- id:String. The kata id.
- index:int. The next event index.
- files:Hash. The current files (old_filename is present; new_filename is not yet present).
- old_filename:String. The current name of the file.
- new_filename:String. The new name of the file.
returns
- the event index to use for the next call.

example

$ curl \
  --data '{"id":"4ScKVJ","index":6,"files":{...},"old_filename":"utils.sh","new_filename":"helpers.sh"}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_file_rename | jq .

{
  "kata_file_rename": 7
}

POST kata_file_edit(id,index,files)

Records a file edit event if any file content has changed since the last save. If no file has changed, no event is recorded and the same index is returned.

parameters
- id:String. The kata id.
- index:int. The next event index.
- files:Hash. The current files.
returns
- the (possibly unchanged) event index to use for the next call.

example

$ curl \
  --data '{"id":"4ScKVJ","index":7,"files":{...}}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_file_edit | jq .

{
  "kata_file_edit": 7
}

POST kata_ran_tests(id,index,files,stdout,stderr,status,summary)

Record a test event with no prediction.

parameters
- id:String. The kata id.
- index:int. The next event index.
- files:Hash. The files which created stdout,stderr,status in the same format as kata_event
- stdout:Hash. The stdout produced from files, in the same format as kata_event
- stderr:Hash. The stderr produced from files, in the same format as kata_event
- status:String. The status produced from files, in the same format as kata_event
- summary:Hash. Extra event data to store, eg duration,time,colour

POST kata_predicted_right(id,index,files,stdout,stderr,status,summary)

Record a test event with a correct prediction.

POST kata_predicted_wrong(id,index,files,stdout,stderr,status,summary)

Record a test event with an incorrect prediction.

POST kata_reverted(id,index,files,stdout,stderr,status,summary)

Revert back to a previous traffic-light.

POST kata_checked_out(id,index,files,stdout,stderr,status,summary)

Checkout a traffic-light from a different avatar.

GET kata_option_get(id,name)

Get a theme (dark/light) or colour (on/off) or prediction (on/off) option.

POST kata_option_set(id,name,value)

Set a theme (dark/light) or colour (on/off) or prediction (on/off) option.

POST kata_fork(id,index)

Creates a new kata whose starting files are a copy of the files in the kata with the given id at the given index. The new kata is not a fork in the git sense; that is, it is not a 'deep' copy, the history of commits (one per test event) that exist in the kata being forked are not copied.

parameters
- id:String.
- index:int
returns
- the id of the created kata.

example

$ curl \
  --data '{"id":"dFg8Us", "index":23}' \
  --fail \    
  --header 'Content-type: application/json' \
  --silent \
  --request POST \
    https://${DOMAIN}:${PORT}/kata_fork | jq .

{
  "kata_fork": "a8gVRN"
}

Diff API

GET diff_lines(id,was_index,now_index)

A diff of two sets of files (designated with was_index and now_index) from the kata with the given id. Every line of every file is returned - not just the changed lines with a few unchanged lines either side as a normal git diff would give. Unchanged files and files renamed with identical content are also included.

parameters
- id:String. The kata id.
- was_index:Integer. The event index of the first set of files.
- now_index:Integer. The event index of the second set of files.
returns
- an Array of Hashes, one per file. Each Hash has the following keys:
  - "type" - one of "created", "deleted", "renamed", "changed", "unchanged".
  - "old_filename" - the filename at was_index, or null if "type" is "created".
  - "new_filename" - the filename at now_index, or null if "type" is "deleted".
  - "lines" - an Array of Hashes, each with "type" ("added", "deleted", "same", or "section").
  - "line_counts" - a Hash with "added", "deleted", and "same" counts.

example

$ curl \
  --data '{"id":"4ScKVJ","was_index":3,"now_index":4}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/diff_lines | jq .

{
  "diff_lines": [
    {
      "type": "changed",
      "old_filename": "hiker.py",
      "new_filename": "hiker.py",
      "lines": [
        { "type": "same",    "line": "class Hiker:", "number": 1 },
        { "type": "section", "index": 0 },
        { "type": "deleted", "line": "    pass",     "number": 2 },
        { "type": "added",   "line": "    def answer(self):", "number": 2 },
        { "type": "added",   "line": "        return 42",    "number": 3 }
      ],
      "line_counts": { "added": 2, "deleted": 1, "same": 1 }
    },
    ...
  ]
}

GET diff_summary(id,was_index,now_index)

The same as diff_lines except the returned Hashes do not include the "lines" key.

parameters
- id:String. The kata id.
- was_index:Integer. The event index of the first set of files.
- now_index:Integer. The event index of the second set of files.
returns
- an Array of Hashes with "type", "old_filename", "new_filename", and "line_counts" (no "lines").

example

$ curl \
  --data '{"id":"4ScKVJ","was_index":3,"now_index":4}' \
  --fail \
  --header 'Content-type: application/json' \
  --silent \
  --request GET \
    https://${DOMAIN}:${PORT}/diff_summary | jq .

{
  "diff_summary": [
    {
      "type": "changed",
      "old_filename": "hiker.py",
      "new_filename": "hiker.py",
      "line_counts": { "added": 2, "deleted": 1, "same": 1 }
    },
    ...
  ]
}

Probe API

GET alive?

Liveness probe - is the service alive?

parameters
- none
result
- true

example

$ curl --fail --silent --request GET https://${DOMAIN}:${PORT}/alive? | jq .

{
  "alive?": true
}

GET ready?

Readiness probe - is the service ready to handle requests?

parameters
- none
result
- true when the service is ready
- false when the service is not ready

example

$ curl --fail --silent --request GET https://${DOMAIN}:${PORT}/ready? | jq .

{
  "ready?": false
}

GET sha

The git commit sha used to create the Docker image.

parameters
- none
result
- the 40 character commit sha string.

example

$ curl --fail --silent --request GET https://${DOMAIN}:${PORT}/sha | jq .

{
  "sha": "41d7e6068ab75716e4c7b9262a3a44323b4d1448"
}

JSON in

All methods pass their argument in a json hash in the http request body.
If there are no arguments you can use '' (which is the default for curl --data) instead of '{}'.

JSON out

All methods return a json hash in the http response body.

If the method does not raise, a string key equals the method's name. eg

$ curl --silent -X GET https://${DOMAIN}:${PORT}/ready? | jq .

{
  "ready?": true
}

If the method raises an exception, a string key equals "exception", with a json-hash as its value. eg

$ curl --data 'not-json-hash' --silent -X GET https://${DOMAIN}:${PORT}/run | jq

{
  "exception": {
    "path": "/run",
    "body": "not-json-hash",
    "class": "SaverService",
    "message": "...",
    "backtrace": [
      ...
      "/usr/bin/rackup:23:in `<main>'"
    ]
  }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API

Group API

POST group_create(manifest)

GET group_manifest(id)

GET group_exists?(id)

POST group_join(id)

GET group_joined(id)

POST group_fork(id,index)

Kata API

POST kata_create(manifest)

GET kata_manifest(id)

GET kata_exists?(id)

GET kata_events(id)

GET kata_event(id,index)

GET katas_events(ids,indexes)

GET kata_download(id)

POST kata_file_create(id,index,files,filename)

POST kata_file_delete(id,index,files,filename)

POST kata_file_rename(id,index,files,old_filename,new_filename)

POST kata_file_edit(id,index,files)

POST kata_ran_tests(id,index,files,stdout,stderr,status,summary)

POST kata_predicted_right(id,index,files,stdout,stderr,status,summary)

POST kata_predicted_wrong(id,index,files,stdout,stderr,status,summary)

POST kata_reverted(id,index,files,stdout,stderr,status,summary)

POST kata_checked_out(id,index,files,stdout,stderr,status,summary)

GET kata_option_get(id,name)

POST kata_option_set(id,name,value)

POST kata_fork(id,index)

Diff API

GET diff_lines(id,was_index,now_index)

GET diff_summary(id,was_index,now_index)

Probe API

GET alive?

GET ready?

GET sha

JSON in

JSON out

FilesExpand file tree

api.md

Latest commit

History

api.md

File metadata and controls

API

Group API

POST group_create(manifest)

GET group_manifest(id)

GET group_exists?(id)

POST group_join(id)

GET group_joined(id)

POST group_fork(id,index)

Kata API

POST kata_create(manifest)

GET kata_manifest(id)

GET kata_exists?(id)

GET kata_events(id)

GET kata_event(id,index)

GET katas_events(ids,indexes)

GET kata_download(id)

POST kata_file_create(id,index,files,filename)

POST kata_file_delete(id,index,files,filename)

POST kata_file_rename(id,index,files,old_filename,new_filename)

POST kata_file_edit(id,index,files)

POST kata_ran_tests(id,index,files,stdout,stderr,status,summary)

POST kata_predicted_right(id,index,files,stdout,stderr,status,summary)

POST kata_predicted_wrong(id,index,files,stdout,stderr,status,summary)

POST kata_reverted(id,index,files,stdout,stderr,status,summary)

POST kata_checked_out(id,index,files,stdout,stderr,status,summary)

GET kata_option_get(id,name)

POST kata_option_set(id,name,value)

POST kata_fork(id,index)

Diff API

GET diff_lines(id,was_index,now_index)

GET diff_summary(id,was_index,now_index)

Probe API

GET alive?

GET ready?

GET sha

JSON in

JSON out