Merge pull request #1603 from dodona-edu/docs/api-url

Change API docs to allow custom URL's
dodona-edu · Oct 3, 2024 · f91375c · f91375c
2 parents 3bb4116 + 47347c3
commit f91375c
Show file tree

Hide file tree

Showing 3 changed files with 88 additions and 18 deletions.
diff --git a/docs/docs/api.md b/docs/docs/api.md
@@ -2,11 +2,79 @@
 outline: [2,3]
 ---
 
+<script setup>
+import { computed } from 'vue';
+import { useStorage } from '@vueuse/core';
+
+const defaultURL = "https://dolos.ugent.be/api";
+const localhostURL = "http://localhost:3000";
+const dolosURL = useStorage("dolos-docs-api-url", "https://dolos.ugent.be/api");
+
+const isDefault = computed(() => dolosURL.value === defaultURL);
+
+function setLocalhost() {
+   dolosURL.value = localhostURL;
+}
+
+function setPublicAPI() {
+   dolosURL.value = defaultURL;
+}
+
+</script>
+<style>
+.url-input {
+	padding: 6px 12px;
+	font-size: inherit;
+	width: 100%;
+	line-height: inherit;
+	color: inherit;
+	border: 1px solid var(--vp-c-divider);
+	border-radius: 4px;
+	display: flex;
+	align-items: center;
+	cursor: text;
+}
+
+.button-row button {
+   background-color: var(--vp-button-alt-bg);
+   color: var(--vp-button-alt-text);
+   border-radius: 20px;
+   padding: 0 20px;
+   margin: 0 5px;
+   line-height: 38px;
+   font-size: 14px;
+   display: inline-block;
+   text-align: center;
+   font-weight: 600;
+   white-space: nowrap;
+   transition: colos 0.25s, border-color 0.25s, background-color 0.25s;
+}
+
+.button-row button.primary {
+   color: var(--vp-button-brand-text);
+   background-color: var(--vp-button-brand-bg);
+}
+</style>
+
 # Dolos API
 
 Dolos provides its JSON API for automated integration with exercise platforms such as [Dodona](https://dodona.be).
 
-The description below works with our publicly hosted instance ([dolos.ugent.be/api](https://dolos.ugent.be/api)) or a [self-hosted](./hosting-dolos) instance.
+<div v-if="isDefault">
+   The description below shows the URL endpoints of our publicly hosted instance (<a href="https://dolos.ugent.be/server">dolos.ugent.be/api</a>).
+</div>
+<div v-else>
+   The description below shows the URL endpoints of your custom URL endpoint. Click one of the buttons to change this back to the public endpoint.
+</div>
+
+Edit the value below to change the endpoint URL used in this documentation:
+
+<input class="url-input" v-model="dolosURL"></input>
+
+<div class="button-row">
+<button :class="isDefault || 'primary'" @click="setPublicAPI">Use public API</button>
+<button @click="setLocalhost">Use localhost API</button>
+</div>
 
 The API currently requires **no authentication**.
 
@@ -17,18 +85,18 @@ You can access the visualisations using the `html_url` returned by the API.
 
 ::: code-group
 
-```shell [Shell]
+```shell-vue [Shell]
 # Requires curl and jq
 # Outputs the URL to the resulting report
 curl --request POST \
     --form "dataset[name]=Example" \
     --form "dataset[zipfile]=@simple-dataset.zip" \
-    https://dolos.ugent.be/api/reports \
+    {{ dolosURL }}/reports \
     | jq -r '.html_url'
  ```
 
-```html [HTML / Javascript]
-<form id="dolos-upload" action="https://dolos.ugent.be/api/reports" >
+```html-vue [HTML / Javascript]
+<form id="dolos-upload" action="{{ dolosURL }}/reports" >
    <input type="text" name="dataset[name]" placeholder="Name" />
    <input type="file" name="dataset[zifile]" />
    <input type="submit" value="Submit" />
@@ -49,7 +117,7 @@ curl --request POST \
 </script>
 ```
 
-```python [Python]
+```python-vue [Python]
 import requests # pip install requests
 
 def submit_to_dolos(name, zipfile_path):
@@ -58,22 +126,22 @@ def submit_to_dolos(name, zipfile_path):
    and return the URL where the resulting HTML report can be found.
    """
    response = requests.post(
-      'https://dolos.ugent.be/api/reports',
+      '{{ dolosURL }}/reports',
       files = { 'dataset[zipfile]': open(zipfile_path, 'rb') },
       data = { 'dataset[name]': name }
    )
    json = response.json()
    return json["html_url"]
 ```
 
-```ruby [Ruby]
+```ruby-vue [Ruby]
 require 'httparty' # bundle install httparty
 
 # Submit a ZIP-file to the Dolos API for plagiarism detection
 # and return the URL where the resulting HTML report can be found.
 def submit_to_dolos(name, zipfile_path)
    response = HTTParty.post(
-     'https://dolos.ugent.be/api/reports',
+     '{{ dolosURL }}/reports',
      body: {
        dataset: {
          name: name,
@@ -137,11 +205,11 @@ The resulting **report files** (`metadata.csv`, `files.csv`, `kgrams.csv` and `p
 
 ### Example JSON
 
-```json
+```json-vue
 {
   "created_at": "2024-03-11T14:11:19.142Z",
   "updated_at": "2024-03-11T14:11:27.666Z",
-  "url": "https://dolos.ugent.be/api/reports/9876543210123456789",
+  "url": "{{ dolosURL }}/reports/9876543210123456789",
   "id": "9876543210123456789",
   "error": null,
   "status": "finished",
@@ -152,10 +220,10 @@ The resulting **report files** (`metadata.csv`, `files.csv`, `kgrams.csv` and `p
   "dataset": {
     "created_at": "2024-03-11T14:11:19.136Z",
     "updated_at": "2024-03-11T14:11:19.141Z",
-    "url": "https://dolos.ugent.be/api/datasets/1234567891234567890",
+    "url": "{{ dolosURL }}/datasets/1234567891234567890",
     "id": "1234567891234567890",
     "programming_language": "",
-    "zipfile": "https://dolos.ugent.be/api/rails/active_storage/blobs/redirect/<...>/example.zip",
+    "zipfile": "{{ dolosURL }}/rails/active_storage/blobs/redirect/<...>/example.zip",
     "name": "Example"
   }
 }
@@ -168,7 +236,7 @@ To submit a ZIP-file for analysis, you need to send a `multipart/form-data` with
 
 #### Request
 
-`POST https://dolos.ugent.be/api/reports`
+`POST {{ dolosURL }}/reports`
 
 | Parameters                    | Type   | Required | Description                                                               |
 |-------------------------------|--------|----------|---------------------------------------------------------------------------|
@@ -211,7 +279,7 @@ If you need the resulting files
 
 #### Request
 
-`GET https://dolos.ugent.be/api/reports/:id`
+`GET {{ dolosURL }}/reports/:id`
 
 #### Response
 
@@ -221,7 +289,7 @@ If a report with the corresponding id exists, the API will return a status `200
 
 #### Request
 
-`GET https://dolos.ugent.be/api/reports/:id/data/:file`
+`GET {{ dolosURL }}/reports/:id/data/:file`
 
 Where `:file` is one of:
 - `metadata`: report metadata (such as detected programming language)
@@ -240,7 +308,7 @@ A report object will still be preserved with status set to `purged`.
 
 #### Request
 
-`DELETE https://dolos.ugent.be/api/reports/:id`
+`DELETE {{ dolosURL }}/reports/:id`
 
 #### Response
 

diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -10,7 +10,8 @@
   "license": "MIT",
   "type": "module",
   "devDependencies": {
-    "vitepress": "^1.1.4"
+    "vitepress": "^1.1.4",
+    "@vueuse/core": "*"
   },
   "scripts": {
     "dev": "vitepress dev",