Make API endpoints documentation (HumanSignal#493)

* Make API endpoints documentation * Fix descs * Escape some chars * Fix enters * Remove : * small edits Co-authored-by: Mikhail Maluyk <[email protected]>
naihetxi · Nov 20, 2020 · cf0269e · cf0269e
1 parent 42a71a8
commit cf0269e
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 73 deletions.
diff --git a/docs/source/guide/api.md b/docs/source/guide/api.md
@@ -0,0 +1,133 @@
+---
+title: Backend API
+type: guide
+order: 907
+---
+
+> These API endpoints were introduced in Label Studio version 0.8.1. Subject to change before version 1.0.0
+
+### Setup project configuration
+
+`POST /api/project/config`
+
+Save labeling config for the project using API: 
+```
+curl -X POST -H Content-Type:application/json http://localhost:8080/api/project/config \
+--data "{\"label_config\": \"<View>[...]</View>\"}"
+```
+
+The backend should return status 201 if the config is valid and saved. 
+If errors occur the backend returns status 400 and the response body will be JSON dict: 
+```
+{
+  "label_config": ["error 1 description", " error 2 description", ...]
+}
+```
+
+### Import data and tasks 
+
+`POST /api/project/import`
+
+Use API to import tasks in [Label Studio basic format](tasks.html#Basic-format) useful when you are creating a data stream.
+
+```bash
+curl -X POST -H Content-Type:application/json http://localhost:8080/api/project/import \
+--data "[{\"my_key\": \"my_value_1\"}, {\"my_key\": \"my_value_2\"}]"
+```
+
+### Retrieve project
+
+`GET /api/project`
+
+You can retrieve project settings including total task count using API in JSON format: 
+
+```json
+curl http://localhost:8080/api/project/
+```
+
+Response example: 
+
+```json
+{
+  ... 
+  "task_count": 3,
+  ...
+}
+```
+
+### Retrieve tasks
+
+`GET /api/tasks`
+
+To get tasks with pagination in JSON format:
+
+```
+curl http://localhost:8080/api/tasks?page=1&page_size=10&order=-completed_at
+```
+
+Response example:
+
+```json
+[
+  {
+    "completed_at": "2020-05-29 03:31:15", 
+    "completions": [
+      {
+        "created_at": 1590712275, 
+        "id": 10001, 
+        "lead_time": 4.0, 
+        "result": [ ... ]
+      }
+    ], 
+    "data": {
+      "image": "s3://htx-dev/dataset/training_set/dogs/dog.102.jpg"
+    }, 
+    "id": 2, 
+    "predictions": []
+  }
+]
+```
+
+`order` can be either one of `id`, `-id`, `completed_at`, `-completed_at`
+
+### Export annotations
+
+`GET /api/project/export`
+
+You can use an API to request a file with all annotations, e.g.
+
+```bash
+curl http://localhost:8080/api/project/export?format=JSON > exported_results.json
+```
+
+The formats descriptions are presented [above](#Export-formats). 
+The `format` parameters could be found on the Export page in the dropdown (`JSON`, `JSON_MIN`, `COCO`, `VOC`, etc).
+
+### Reference
+
+| URL | Description |
+| --- | --- |
+| **Project** |
+| /api/project                      | `GET` return project settings and states (like task and completion counters) <br> `POST` create a new project for multi-session-mode with `desc` field from request args as project title <br> `PATCH` update project settings |
+| /api/project/config               | `POST` save project configuration (labeling config, etc) |
+| /api/project/import               | `POST` import data or annotations |
+| /api/project/export               | `GET` downalod annotations, pass `format` param to specify the format |
+| /api/project/next                 | `GET` return next task available for labeling |
+| /api/project/storage-settings     | `GET` current storage settings <br> `POST` set storage settings |
+| /api/project-switch               | `GET` switch to specified project by project UUID in multi-session mode |
+| **Tasks** |
+| /api/tasks                        | `GET` retrieve all tasks from project <br> `DELETE` delete all tasks from project |
+| /api/tasks/\<task_id>              | `GET` retrieve specific task <br> `DELETE` delete specific task  |
+| /api/tasks/\<task_id>/completions  | `POST` create a new completion <br> `DELETE` delete all task completions |
+| /api/tasks/\<task_id>/completions/\<completion_id> | `PATCH` update completion <br> `DELETE` delete completion |
+| /api/completions                  | `GET` returns all completion ids <br> `DELETE` delete all project completions |
+| **Machine Learning Models** | 
+| /api/models                       | `GET` list all models <br> `DELETE` remove model with `name` field from request json body |  
+| /api/models/train                 | `POST` send training signal to ML backend | 
+| /api/models/predictions?mode={data\|all_tasks} | `GET \| POST`<br> `mode=data`: generate ML model predictions for one task from `data` field of request json body<br> `mode=all_tasks`: generate ML model predictions for all LS DB tasks | 
+| **Helpers** |
+| /api/validate-config              | `POST` check labeling config for errors |
+| /api/import-example               | `GET \| POST` generate example for import by given labeling config |
+| /api/import-example-file          | `GET` generate example file for import using current project labeling config | 
+| /api/health                       | `GET` health check |
+| /version                          | `GET` current Label Studio Backend and Frontend versions |
diff --git a/docs/source/guide/export.md b/docs/source/guide/export.md
@@ -207,11 +207,4 @@ Export your brushe labels to numpy 2d arrays and PNG images. One label is equal
 
 ## Export using API
 
-You can use an API to request a file with exported results, e.g.
-
-```bash
-curl http://localhost:8080/api/export?format=JSON > exported_results.zip
-```
-
-The formats description are presented [above](#Export-formats). 
-The `format` parameters could be found on Export page in the dropdown (JSON, JSON_MIN, COCO, VOC, etc).   
+You can export results using server API. Check [API page](api.html) for more details.
diff --git a/docs/source/guide/setup.md b/docs/source/guide/setup.md
@@ -66,16 +66,4 @@ You can also use the web interface at [`/setup`](http://localhost:8080/setup) to
 
 ### Setup labeling config from API
 
-Save labeling config for the project using API: 
-```
-curl -X POST -H Content-Type:application/json http://localhost:8080/api/save-config \
---data "{\"label_config\": \"<View>[...]</View>\"}"
-```
-
-The backend should return status 201 if config is valid and saved. 
-If errors occur the backend returns status 400 and response body will be JSON dict: 
-```
-{
-  "label_config": ["error 1 description", " error 2 description", ...]
-}
-```
+You can configure your labeling config via server API. Check [Backend API page](api.html) for more details.
diff --git a/docs/source/guide/tasks.md b/docs/source/guide/tasks.md
@@ -186,59 +186,8 @@ For label configs with one data key (e.g.: one input image) Label Studio support
 
 ## Import using API
 
-Use API to import tasks in [Label Studio basic format](tasks.html#Basic-format) if for any reason you can't access either a local filesystem nor Web UI (e.g. if you are creating a data stream)
+Import your data using server API. Check [API page](api.html) for more details.
 
-```bash
-curl -X POST -H Content-Type:application/json http://localhost:8080/api/import \
---data "[{\"my_key\": \"my_value_1\"}, {\"my_key\": \"my_value_2\"}]"
-```
-
-## Retrieve tasks using API
-
-You can retrieve project settings including total task count using API in JSON format: 
-
-```json   
-http://<host:port>/api/project
-```
-
-Response example: 
-
-```json
-{
-  ... 
-  "task_count": 3,
-  ...
-}
-```
-
-To get tasks with pagination in JSON format:
-
-```
-http://<host:port>/api/tasks?page=1&page_size=10&order={-}[id|completed_at]
-```
-
-Response example:
-
-```json
-[
-  {
-    "completed_at": "2020-05-29 03:31:15", 
-    "completions": [
-      {
-        "created_at": 1590712275, 
-        "id": 10001, 
-        "lead_time": 4.0, 
-        "result": [ ... ]
-      }
-    ], 
-    "data": {
-      "image": "s3://htx-dev/dataset/training_set/dogs/dog.102.jpg"
-    }, 
-    "id": 2, 
-    "predictions": []
-  }
-]
-```
 
 ## Sampling