From ed335313ce800edf458ecbc6851e17539572235f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Sun, 2 Oct 2022 18:13:31 +0300 Subject: [PATCH 1/7] Create header.template.ru.md RU locale documentation header --- ApiDocJs/shared/header.template.ru.md | 347 ++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 ApiDocJs/shared/header.template.ru.md diff --git a/ApiDocJs/shared/header.template.ru.md b/ApiDocJs/shared/header.template.ru.md new file mode 100644 index 0000000..903d3b9 --- /dev/null +++ b/ApiDocJs/shared/header.template.ru.md @@ -0,0 +1,347 @@ +## **Обзор** + +Вот некоторая информация, которая должна помочь вам понять основы использования нашего RESTful API. Включая информацию об аутентификации пользователей, выполнении запросов, ответов, +потенциальных ошибках, ограничении скорости, нумерации страниц, параметрах запроса и многом другом. + +## **Заголовки** + +Некоторые вызовы API требуют, чтобы вы отправляли данные в определенном формате. +По умолчанию все вызовы API ожидают ввода в JSONформате, однако вам необходимо сообщить серверу, +что вы ожидаете полезную нагрузку в формате JSON. +А для этого вы должны включать Accept => application/json HTTP-заголовок при каждом вызове. + + +| Заголовок | Образенц значения | Когда отправлять | +|---------------|-------------------------------------|--------------------------------------------------------------------| +| Accept | `application/json` | ДОЛЖЕН быть в КАЖДОМ запросе | +| Content-Type | `application/x-www-form-urlencoded` | ДОЛЖЕН быть отправлен при передаче данных | +| Authorization | `Bearer {Access-Token-Here}` | ДОЛЖЕН быть отправлен всякий раз, когда запрос требует авторизации | + +## **Rate limiting** + +Все запросы REST API регулируются для предотвращения злоупотреблений и обеспечения стабильности. +Точное количество вызовов, которое ваше приложение может совершать в день, зависит от типа отправляемого вами запроса. + +Окно ограничения скорости составляет `{{rate-limit-expires}}` минут на endpoint, при этом большинство отдельных вызовов допускают `{{rate-limit-attempts}}` запросов в каждом окне. + +*Другими словами, каждому пользователю разрешено совершать `{{rate-limit-attempts}}` вызовов на endpoint каждые `{{rate-limit-expires}}` минут. (Для каждого уникального токена доступа).* + +Сколько запросов вы можете выполнить на endpoint, вы всегда можете проверить в заголовке: + +``` +X-RateLimit-Limit → 30 +X-RateLimit-Remaining → 29 +``` + +## **Tokens** + +Токен доступа действителен `{{access-token-expires-in}}`. (`{{access-token-expires-in-minutes}}` минут). +Refresh Token действителен `{{refresh-token-expires-in}}`. (`{{refresh-token-expires-in-minutes}}` минут). + +*Вам нужно будет повторно аутентифицировать пользователя, когда срок действия токена истечет.* + +## **Pagination** + +По умолчанию, все запросы с пагинацией возвращают первые `{{pagination-limit}}` элементов в списке. Прочтите раздел **Query Parameters**, чтобы узнать, как управлять нумерацией страниц. + + + +## **Limit:** + +Параметр `?limit=` может быть применен для указания сколько записей должно быть возвращено в ответе (Прочтите раздел `Pagination`!). + +**Использование:** + +``` +api.domain.test/v1/endpoint?limit=100 +``` + +Приведенный выше пример возвращает 100 ресурсов. + +Параметры запроса `limit` и `page` можно комбинировать, чтобы получить следующие 100 ресурсов: + +``` +api.domain.test/v1/endpoint?limit=100&page=2 +``` + +Вы можете отключить ограничение пагинацию, чтобы получить все данные, указав `?limit=0`, это будет работать только в том случае, если на сервере включен параметр 'skip pagination'. + +## **Responses** + +Если не указано иное, все конечные точки API будут возвращать запрашиваемую вами информацию в формате JSON. + + +#### Standard Response Format + +```json +{ + "data": { + "object": "Role", + "id": "owpmaymq", + "name": "admin", + "description": "Administrator", + "display_name": null, + "permissions": { + "data": [ + { + "object": "Permission", + "id": "wkxmdazl", + "name": "update-users", + "description": "Update a User.", + "display_name": null + }, + { + "object": "Permission", + "id": "qrvzpjzb", + "name": "delete-users", + "description": "Delete a User.", + "display_name": null + } + ] + } + } +} +``` + +#### Header + +Header Response: + +``` +Content-Type → application/json +Date → Thu, 14 Feb 2014 22:33:55 GMT +ETag → "9c83bf4cf0d09c34782572727281b85879dd4ff6" +Server → nginx +Transfer-Encoding → chunked +X-Powered-By → PHP/7.0.9 +X-RateLimit-Limit → 100 +X-RateLimit-Remaining → 99 +``` + +## **Query Parameters** + +Параметры запроса являются необязательными, вы можете применить их к некоторым конечным точкам, когда они вам понадобятся. + +### Ordering + +Параметр `?orderBy=` может применяться к любому **`GET`** HTTP запросу чтобы упорядочить список записей в ответе по полю. + +**Использование:** + +``` +api.domain.test/v1/endpoint?orderBy=created_at +``` + +### Sorting + +Параметр `?sortedBy=` обычно используется вместе с `orderBy`. + +По умолчанию `orderBy` сортирует данные в порядке **возрастания** если вы хотите, чтобы данные сортировались в порядке **убывания**, вы можете добавить `&sortedBy=desc`. + +**Использование:** + +``` +api.domain.test/v1/endpoint?orderBy=name&sortedBy=desc +``` + +Доступные параметры сортировки: + +- `asc` для сортировки по Возрастанию. +- `desc` для сортировки по Убыванию. + +### Поиск + +Если [RequestCriteria](http://apiato.io/docs/core-features/query-parameters#using-the-request-criteria) +включен для маршрута, то `?search=` параметр может быть использован для этого **`GET`** HTTP запроса. + +**Использование:** + +#### Поиск по любому из полей: + +``` +api.domain.test/v1/endpoint?search=keyword here +``` + +> Пробел нужно заменить на спецсимвол `%20` (search=keyword%20here). + +#### Поиск в любом поле по нескольким ключевым словам: + +``` +api.domain.test/v1/endpoint?search=first keyword;second keyword +``` + +#### Поиск по определённому полю: +``` +api.domain.test/v1/endpoint?search=field:keyword here +``` + +#### Поиск в определенных полях по нескольким ключевым словам: +``` +api.domain.test/v1/endpoint?search=field1:first field keyword;field2:second field keyword +``` + +#### Условия запроса: + +``` +api.domain.test/v1/endpoint?search=field:keyword&searchFields=name:like +``` + +Доступные условия: + +- `like`: строка похожа на образец. (SQL query `%keyword%`). +- `=`: точное совпадение строки. + + +#### Определить условия запроса для нескольких полей: + +``` +api.domain.test/v1/endpoint?search=field1:first keyword;field2:second keyword&searchFields=field1:like;field2:=; +``` + +#### Комбинированный поиск: +По умолчанию, поиск выполняется используя оператор сравнения ИЛИ для каждого параметра запроса. + +``` +api.domain.test/v1/endpoint?search=age:17;email:john@gmail.com +``` + +В приведенном выше примере будет выполнен следующий запрос: + +```sql +SELECT * FROM users WHERE age = 17 OR email = 'john@gmail.com'; +``` +Чтобы он выполнял запрос с использованием И, передайте `searchJoin` параметр, как показано ниже: + +``` +api.domain.test/v1/endpoint?search=age:17;email:john@gmail.com&searchJoin=and +``` + +### Фильтрация + +Параметр `?filter=` может применяться к любому HTTP-запросу. И используется для управления размером ответа, определяя, какие данные вы хотите включить в ответ. + +**Использование:** + +Возвращает только ID и Status из модели. + +``` +api.domain.test/v1/endpoint?filter=id;status +``` + +Пример ответа, включающий только идентификатор и статус: + +```json +{ + "data": [ + { + "id": "0one37vjk49rp5ym", + "status": "approved", + "products": { + "data": [ + { + "id": "bmo7y84xpgeza06k", + "status": "pending" + }, + { + "id": "o0wzxbg0q4k7jp9d", + "status": "fulfilled" + } + ] + }, + "recipients": { + "data": [ + { + "id": "r6lbekg8rv5ozyad" + } + ] + }, + "store": { + "data": { + "id": "r6lbekg8rv5ozyad" + } + } + } + ] +} +``` + + +### Пагинация + +Параметр `?page=` может быть применен к любому **`GET`** HTTP-запросу возвращающему много записей в ответе (в основном для разбивки на страницы). + +**Использование:** + +``` +api.domain.test/v1/endpoint?page=200 +``` + +*Объект пагинации всегда возвращается в объекте **meta** если разбиение на страницы доступно для эндпоинта.* + +```json + "data": [...], + "meta": { + "pagination": { + "total": 2000, + "count": 30, + "per_page": 30, + "current_page": 22, + "total_pages": 1111, + "links": { + "previous": "http://api.domain.test/v1/endpoint?page=21" + } + } + } +``` + +### Отношения + +Параметр `?include=` может быть использован с любым поддерживаемым его эндпоинтом. + +Как использовать: допустим, есть объект Driver и объект Car. И есть эндпоинт `/cars` который возвращает все объекты cars. +Параметр `?include=` позволяет получить автомобили с их водителями `/cars?include=drivers`. + +Однако для того, чтобы этот параметр работал, эндпоинт `/cars` должен чётко определить, что он принимает +`driver` в качестве отношения (отображается в `include` объекте ответа). + +**Использование:** + +``` +api.domain.test/v1/endpoint?include=relationship +``` + +Каждый ответ содержит `include` в объекте `meta`: + +``` + "meta":{ + "include":[ + "relationship-1", + "relationship-2", + ], +``` + + +### Кэширование + +Некоторые конечные точки сохраняют свои данные ответа в памяти (кэше) после первого запроса, чтобы ускорить время ответа. +Параметр `?skipCache=` можно использовать, чтобы принудительно пропустить загрузку данных ответа из кэша сервера и вместо этого получить свежие данные из базы данных по запросу. + +**Использование:** + +``` +api.domain.test/v1/endpoint?skipCache=true +``` + +## **Requests** + +Пример вызова эндпойнта без авторизации: + +```shell +curl -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded; -F "email=admin@admin.com" -F "password=admin" -F "=" "http://api.domain.test/v2/register" +``` + +Пример вызова эндпойнта с авторизацией (передача Bearer Token): + +```shell +curl -X GET -H "Accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." -H "http://api.domain.test/v1/users" +``` From 304ec8b36886dd424468685748a59ede7450d339 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Sun, 2 Oct 2022 18:30:12 +0300 Subject: [PATCH 2/7] Update vendor-documentation.php --- Configs/vendor-documentation.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Configs/vendor-documentation.php b/Configs/vendor-documentation.php index 73f1db1..d913a16 100644 --- a/Configs/vendor-documentation.php +++ b/Configs/vendor-documentation.php @@ -1,6 +1,17 @@ env('APIDOC_LOCALE'), /* |-------------------------------------------------------------------------- From 6a06da5b9dd7170c648f777ca8a278831dd60725 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Sun, 2 Oct 2022 18:31:10 +0300 Subject: [PATCH 3/7] Update RenderTemplatesTask.php Add locale --- Tasks/RenderTemplatesTask.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Tasks/RenderTemplatesTask.php b/Tasks/RenderTemplatesTask.php index 5ac1e50..6919645 100644 --- a/Tasks/RenderTemplatesTask.php +++ b/Tasks/RenderTemplatesTask.php @@ -15,7 +15,7 @@ class RenderTemplatesTask extends Task public function __construct() { - $this->templatePath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/ApiDocJs/shared/header.template.md'; + $this->templatePath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/ApiDocJs/shared/header.template'.config('vendor-documentation.locale', '').'.md'; $this->outputPath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/UI/WEB/Views/documentation/header.md'; $this->replaceArray = [ 'api.domain.test' => config('apiato.api.url'), From 32c723648621ee896250f88f0c9093030c763f0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Sun, 2 Oct 2022 18:37:29 +0300 Subject: [PATCH 4/7] Update vendor-documentation.php --- Configs/vendor-documentation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Configs/vendor-documentation.php b/Configs/vendor-documentation.php index d913a16..4cb40d9 100644 --- a/Configs/vendor-documentation.php +++ b/Configs/vendor-documentation.php @@ -11,7 +11,7 @@ | */ - 'locale' => env('APIDOC_LOCALE'), + 'locale' => '.'.env('APIDOC_LOCALE'), /* |-------------------------------------------------------------------------- From 1c6392906a61666ecac2cb0ee5c48aae84a98709 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:54:09 +0300 Subject: [PATCH 5/7] Rename header.template.md to header.template.en.md --- ApiDocJs/shared/{header.template.md => header.template.en.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ApiDocJs/shared/{header.template.md => header.template.en.md} (100%) diff --git a/ApiDocJs/shared/header.template.md b/ApiDocJs/shared/header.template.en.md similarity index 100% rename from ApiDocJs/shared/header.template.md rename to ApiDocJs/shared/header.template.en.md From 57bdb4329646e64d536c5946c326a4bea26ddf40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:54:52 +0300 Subject: [PATCH 6/7] Update RenderTemplatesTask.php --- Tasks/RenderTemplatesTask.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Tasks/RenderTemplatesTask.php b/Tasks/RenderTemplatesTask.php index 6919645..2d54e78 100644 --- a/Tasks/RenderTemplatesTask.php +++ b/Tasks/RenderTemplatesTask.php @@ -15,7 +15,7 @@ class RenderTemplatesTask extends Task public function __construct() { - $this->templatePath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/ApiDocJs/shared/header.template'.config('vendor-documentation.locale', '').'.md'; + $this->templatePath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/ApiDocJs/shared/header.template'.config('vendor-documentation.locale', 'en').'.md'; $this->outputPath = 'Containers/' . config('vendor-documentation.section_name') . '/Documentation/UI/WEB/Views/documentation/header.md'; $this->replaceArray = [ 'api.domain.test' => config('apiato.api.url'), From f6b73ca8f9d7ddbcf55cab91da6f03662dcb0ae9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B3=D0=BE=D1=80=D1=8C=20=D0=94=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2?= <59930161+polarikus@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:59:19 +0300 Subject: [PATCH 7/7] Update vendor-documentation.php Set default locale in en --- Configs/vendor-documentation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Configs/vendor-documentation.php b/Configs/vendor-documentation.php index 4cb40d9..d56b36d 100644 --- a/Configs/vendor-documentation.php +++ b/Configs/vendor-documentation.php @@ -11,7 +11,7 @@ | */ - 'locale' => '.'.env('APIDOC_LOCALE'), + 'locale' => '.'.env('APIDOC_LOCALE', 'en'), /* |--------------------------------------------------------------------------