From 46b8ad1ba9085e32532304e8ab10155a6d1e3233 Mon Sep 17 00:00:00 2001
From: yukkop <hectic.yukkop@gmail.com>
Date: Tue, 21 Jan 2025 11:43:05 +0000
Subject: [PATCH] docs: reast standart init

---
 REST_STANDART.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 REST_STANDART.md

diff --git a/REST_STANDART.md b/REST_STANDART.md
new file mode 100644
index 0000000..c0aa5b4
--- /dev/null
+++ b/REST_STANDART.md
@@ -0,0 +1,167 @@
+База на которой основанны запросы
+```mermaid
+erDiagram
+    PEOPLE ||--|{ ORDERS : "id -> person_id"
+    
+    PEOPLE {
+        int id PK
+        string name
+        int age
+        string status
+        boolean active
+        date created_at
+    }
+    
+    ORDERS {
+        int id PK
+        int person_id FK
+        date order_date
+        decimal total
+    }
+```
+
+# Базовый запрос
+```http
+GET /people
+```
+
+Вернёт все доступные записи таблицы.
+
+# Фильтры и условия
+```http
+GET /people?колонка=оператор.значение
+```
+
+## Основные операторы
+- `eq` — равно `?age=eq.20`
+- `gt` / `gte` — больше / больше либо равно `?age=gt.18`
+- `neq` — не равно `?age=neq.20`
+- `lt` / `lte` — меньше / меньше либо равно `?age=lt.65`
+- `like` / `ilike` — шаблон (регистр учитывается / не учитывается) `?name=ilike.*alex*`
+- `in` — входит в набор `?id=in.(1,2,3)`
+- `not.in` — не входит в набор `?id=not.in.(1,2,3)`
+- `match` / `imatch` — [patern matching documentation](https://www.postgresql.org/docs/current/functions-matching.html)
+- `isdistinct` - !=, но можно использовать с NULL `?age=neq.null`
+- `is` — проверка на NULL (или true/false) `?status=is.null` / `?active=is.true`
+
+## Логические операторы (объединение)
+- `and` — несколько условий вместе
+`?and=(status.eq.active,age.gt.18)`
+- `or` — логическое «или»
+`?or=(name.eq.John,name.eq.Mike)`
+- `all`
+
+## Поноценный поиск по тексту
+<!-- TODO: нормальное описание -->
+- `fts` - по по...
+- `plfts` - поиск по по тексту
+- `phfts` - поиск по фразам
+- `wfts` - поиск по словам
+
+# Селекторы (выбор колонок)
+```http
+GET /people?select=id,name,age
+```
+Вернёт только указанные колонки.
+
+## Переименование полей
+```http
+GET /people?select=person_id:id,person_name:name
+```
+Вернёт указанные колонки с указанными именами.
+```json
+[
+  {
+    "person_id": null,
+    "person_name": null
+  }
+]
+```
+
+## Многоуровневый селект
+Если есть связь, например `people` → `orders` (по `people.id = orders.person_id`), то:
+```http
+GET /people?select=id,name,orders(*)
+```
+Вернёт людей вместе со всеми их заказами.
+```json
+[
+  {
+    "id": null,
+    "name": null,
+    "orders": [
+      ...
+    ]
+  }
+  ...
+]
+```
+```http
+GET /people?order=id,total,person(id, name)
+```
+Вернёт заказы вместе с заказчиками.
+```json
+[
+  {
+    "id": null,
+    "total": null,
+    "person": {
+      "id": null,
+      "name": null
+    }
+  }
+  ...
+]
+```
+```http
+GET /people?order=id,total,...person(name)
+```
+Вернёт заказ встроив поля заказчика на верхний уровень.
+```json
+[
+  {
+    "id": null,
+    "total": null,
+    "name": null
+  }
+  ...
+]
+```
+
+# Сортировка
+```http
+GET /people?order=age.desc
+```
+Сортировка по колонке `age` в обратном порядке.
+Может быть цепочка: `?order=age.desc,name.asc`
+
+# Лимиты и сдвиги
+```http
+GET /people?limit=10&offset=20
+```
+Вернёт 10 записей начиная с 21-й.
+
+# Агрегации
+Для агрегаций есть расширенный синтаксис:
+
+- `count=exact` вернёт общее кол-во строк в заголовке `Content-Range`.
+- `Prefer: count=exact` в заголовке запроса даёт то же самое.
+
+## Пример: агрегированные поля
+<!-- TODO: -->
+
+# Пример комбинированного запроса
+Вернуть людей:
+
+- Только id, name.
+- Возраст > 18.
+- Отсортировать по убыванию по created_at.
+- Вернуть не более 5 записей.
+
+```http
+GET /people
+  ?select=id,name
+  &age=gt.18
+  &order=created_at.desc
+  &limit=5
+```