From e78bd06dd1b734ce41e05f0020a02f622235a094 Mon Sep 17 00:00:00 2001
From: Timur Osmanov <54434686+TOsmanov@users.noreply.github.com>
Date: Thu, 10 Jun 2021 20:42:24 +0300
Subject: [PATCH] Add REST API guide in documentation (#3307)

* add rest api guide

* fix linter error
---
 README.md                                     | 11 +----
 .../en/docs/for-developers/REST_API_guide.md  | 43 +++++++++++++++++++
 2 files changed, 44 insertions(+), 10 deletions(-)
 create mode 100644 site/content/en/docs/for-developers/REST_API_guide.md

diff --git a/README.md b/README.md
index 3e4954e5..c4cbb630 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ annotation team. Try it online [cvat.org](https://cvat.org).
 - [Contributing](https://openvinotoolkit.github.io/cvat/docs/for-developers/contributing/)
 - [Installation guide](https://openvinotoolkit.github.io/cvat/docs/for-users/installation/)
 - [User's guide](https://openvinotoolkit.github.io/cvat/docs/for-users/user-guide/)
-- [Django REST API documentation](#rest-api)
+- [Django REST API documentation](https://openvinotoolkit.github.io/cvat/docs/for-developers/rest_api_guide/)
 - [Datumaro dataset framework](https://github.com/openvinotoolkit/datumaro/blob/develop/README.md)
 - [Command line interface](https://openvinotoolkit.github.io/cvat/docs/for-developers/cli/)
 - [XML annotation format](https://openvinotoolkit.github.io/cvat/docs/for-developers/xml_format/)
@@ -116,15 +116,6 @@ Prebuilt docker images for CVAT releases are available on Docker Hub:
 - [cvat_server](https://hub.docker.com/r/openvino/cvat_server)
 - [cvat_ui](https://hub.docker.com/r/openvino/cvat_ui)
 
-## REST API
-
-Automatically generated Swagger documentation for Django REST API is available
-on `<cvat_origin>/api/swagger`(default: `localhost:8080/api/swagger`).
-
-Swagger documentation is visible on allowed hosts, Update environment
-variable in docker-compose.yml file with cvat hosted machine IP or domain
-name. Example - `ALLOWED_HOSTS: 'localhost, 127.0.0.1'`.
-
 ## LICENSE
 
 Code released under the [MIT License](https://opensource.org/licenses/MIT).
diff --git a/site/content/en/docs/for-developers/REST_API_guide.md b/site/content/en/docs/for-developers/REST_API_guide.md
new file mode 100644
index 00000000..5ba6c657
--- /dev/null
+++ b/site/content/en/docs/for-developers/REST_API_guide.md
@@ -0,0 +1,43 @@
+---
+title: 'REST API guide'
+linkTitle: 'REST API'
+weight: 12
+---
+
+To access swagger documentation you need to be authorized.
+
+Automatically generated Swagger documentation for Django REST API is available
+on `<cvat_origin>/api/swagger`(default: `localhost:8080/api/swagger`).
+
+Swagger documentation is visible on allowed hosts, Update environment
+variable in docker-compose.yml file with cvat hosted machine IP or domain
+name. Example - `ALLOWED_HOSTS: 'localhost, 127.0.0.1'`.
+
+Make a request to a resource stored on a server and the server will respond with the requested information.
+The HTTP protocol is used to transport a data.
+Requests are divided into groups:
+
+- `auth` - user authorization queries
+- `comments` - requests to post/delete comments to issues
+- `issues` - update, delete and view problem comments
+- `jobs` -requests to manage the job
+- `lambda` - requests to work with lambda function
+- `projects` - project management queries
+- `restrictions` - requests for restrictions
+- `reviews` -adding and removing the review of the job
+- `server` - server information requests
+- `tasks` - requests to manage tasks
+- `users` -  user management queries
+
+Besides it contains `Models`.
+Models - the data type is described using a 
+[schema object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject).
+
+Each group contains queries related to a different types of HTTP methods such as: `GET`, `POST`, `PATCH`, `DELETE`, etc.
+Different methods are highlighted in different color. Each item has a name and description.
+Clicking on an element opens a form with a name, description and settings input field or an example of json values.
+
+To find out more, read [swagger specification](https://swagger.io/docs/specification/about/).
+
+To try to send a request, click `Try it now `and type `Execute`.
+You'll get a response in the form of [`Curl`](https://curl.se/), `Request URL` and `Server response`.