REST API (кез келген HTTP қызметі)

Қосылым баптаулары, міндетті өрістер және пайдалану ережелері.

Мақсаты

Кез келген HTTP қызметі: жазбаларды оқу (JSON, XML, CSV/TSV, JSON Lines) және жолдарды жіберу (JSON, XML, пішін деректері, CSV). Бір қосылым бір API ресурсы мен сұрау әдісін білдіреді; басқа ресурс не әдіс үшін басқа қосылым жасаңыз.

Қосылым өрістері

REST API қосылымының өрістері. REST API пішінінің жоғарғы бөлігі: атау, қызмет, негізгі мекенжай, аутентификация және қосымша тақырыптар. api.example — оқу мекенжайы. — **REST API қосылымының өрістері**
REST API пішінінің жоғарғы бөлігі: атау, қызмет, негізгі мекенжай, аутентификация және қосымша тақырыптар. api.example — оқу мекенжайы.

Өріс	Ереже және әдепкі мән	Түсіндірме
API негізгі мекенжайы `base_url`	Міндетті	Мәнді қызмет конфигурациясына сәйкес орнатыңыз.
Аутентификация `auth`	Баптауға сәйкес Әдепкі: `none`	`none` — Аутентификациясыз `basic` — Basic (пайдаланушы аты және құпиясөз) `bearer` — Bearer токені `api_key` — Тақырыптағы API кілті `oauth2` — OAuth 2.0 клиент тіркелгі деректері
Пайдаланушы `username`	Баптауға сәйкес	auth = basic болғанда көрсетіледі
API кілтінің тақырыбы `header_name`	Баптауға сәйкес Әдепкі: `X-API-Key`	auth = api_key болғанда көрсетіледі
Токен түпкі нүктесінің мекенжайы `token_url`	Баптауға сәйкес	auth = oauth2 болғанда көрсетіледі
Client ID `client_id`	Баптауға сәйкес	auth = oauth2 болғанда көрсетіледі
Scope (міндетті емес) `scope`	Баптауға сәйкес	auth = oauth2 болғанда көрсетіледі
Қосымша тақырыптар `headers`	Баптауға сәйкес	Әр жолға біреу: «Атау: мән». Құпия деректерді мұнда емес, құпия өріске енгізіңіз.
Жауапты күту уақыты, секунд `timeout`	Баптауға сәйкес Әдепкі: `60` Ауқым: 1–600	Мәнді қызмет конфигурациясына сәйкес орнатыңыз.
Ресурс жолы `resource_path`	Баптауға сәйкес	Негізгі мекенжайға қатысты, сұрау параметрлерінсіз (? …). Жеке сұрауларда жолға кесте өрісін енгізуге болады: /orders/{{Number}}.
Сұрау әдісі `method`	Баптауға сәйкес Әдепкі: `GET`	`GET` — GET — оқу `POST` — POST — сұрау денесімен оқу немесе жолдарды жіберу `PUT` — PUT — жолдарды жіберу (алмастыру) `PATCH` — PATCH — жолдарды жіберу (жаңарту)
Негізгі сұрау параметрлері `query_params`	Баптауға сәйкес	Осы қосылымды қолданатын әр сұрауға қосылады. Әр жолға біреу: «name=value» немесе тек «name» (мысалы, json). Мәндер автоматты кодталады. Дереккөз блогы өз параметрлерін қоса алады.
Сұрау денесінің пішімі `request_format`	Баптауға сәйкес Әдепкі: `json`	Жолдарды жіберуге және POST оқу сұрауының денесіне арналған. `json` — JSON `xml` — XML `form` — Пішін (application/x-www-form-urlencoded) `csv` — CSV — бөлгіші бар мәтін method = POST, PUT, PATCH болғанда көрсетіледі
Сұрау денесі `body`	Баптауға сәйкес	Тек POST оқу үшін, таңдалған дене пішімінде (пішін деректері үшін әр жолға бір «name=value»). Жібергенде сұрау денесін кесте жолдары құрайды және бұл өріс қолданылмайды. method = POST болғанда көрсетіледі
XML жол элементі `xml_record`	Баптауға сәйкес Әдепкі: `record`	Әр жол осы атаудағы элемент ретінде жіберіледі; бағандар оның еншілес элементтері болады. method = POST, PUT, PATCH және request_format = xml болғанда көрсетіледі
Жауап пішімі `response_format`	Баптауға сәйкес Әдепкі: `auto`	`auto` — Автоматты анықтау (Content-Type бойынша) `json` — JSON `xml` — XML `csv` — CSV/TSV — бөлгіші бар мәтін `jsonl` — JSON Lines (NDJSON) — әр жолға бір JSON нысаны method = GET, POST болғанда көрсетіледі
Жауап кодтауы `response_encoding`	Баптауға сәйкес Әдепкі: `auto`	Автоматты: Content-Type немесе XML декларациясынан; әйтпесе UTF-8. `auto` — Автоматты `utf-8` — UTF-8 `windows-1251` — Windows-1251 `iso-8859-1` — ISO-8859-1 (Latin-1) method = GET, POST болғанда көрсетіледі
CSV бөлгіші `csv_delimiter`	Баптауға сәйкес Әдепкі: `comma`	`comma` — Үтір ( , ) `semicolon` — Нүктелі үтір ( ; ) `tab` — Табуляция (TSV) `pipe` — Тік сызық ( \| ) Қолжетімділігі сұрау әдісі мен пішіміне тәуелді.
Жауаптың алғашқы CSV жолында баған атаулары бар `csv_header`	Баптауға сәйкес Әдепкі: `True`	method = GET, POST және response_format = csv болғанда көрсетіледі
Жауаптағы жазбалар жолы `records_path`	Баптауға сәйкес	JSON: нүктемен бөлінген жол (data.items); бос мән жазбалар массивін немесе бір массиві бар нысанды білдіреді. XML: түбірден басталатын элемент жолы (./item, ./data/item, .//item); бос мән қайталанатын элементтерді — бірдей элементтердің ең үлкен тобын (қарапайым тізімде түбірдің еншілестерін) білдіреді. Ішкі нысандар мен элементтер «a.b» бағандарына, XML атрибуттары «@name» бағандарына айналады. method = GET, POST және response_format = auto, json, xml болғанда көрсетіледі
XML жазбаларына ата-аналық элемент атрибуттарын қосу `xml_ancestors`	Баптауға сәйкес Әдепкі: `True`	Әр жазба түбір мен сол жазба арасындағы элементтердің атрибуттарын алады. Мысалы, ECB валюта бағамдарында Cube.Cube.@time күні әр валюта жолына қосылады. Баған атауы түбірден элемент жолы және «@attribute» бөлігінен тұрады; жазбаның өз өрісі басымдыққа ие. method = GET, POST және response_format = auto, xml болғанда көрсетіледі
Жауап беттері `pagination`	Баптауға сәйкес Әдепкі: `none`	`none` — Бір жауап `next_link` — Жауап денесіндегі келесі бет сілтемесі (JSON, XML) `link_header` — Link тақырыбындағы келесі бет сілтемесі (rel="next") `page` — Параметрдегі бет нөмірі `offset` — Параметрдегі ығысу method = GET, POST болғанда көрсетіледі
Келесі бет сілтемесінің жолы `next_link_path`	Баптауға сәйкес Әдепкі: `next`	JSON: нүктемен бөлінген жол; XML: элемент жолы (элемент мәтіні) немесе «path@attribute». Сілтеме сол серверге апаруы керек. method = GET, POST және pagination = next_link болғанда көрсетіледі
Бет нөмірі немесе ығысу параметрі `page_param`	Баптауға сәйкес Әдепкі: `page`	method = GET, POST және pagination = page, offset болғанда көрсетіледі
Бет өлшемінің параметрі (міндетті емес) `size_param`	Баптауға сәйкес	method = GET, POST және pagination = page, offset болғанда көрсетіледі
Бет өлшемі `page_size`	Баптауға сәйкес Әдепкі: `100` Ауқым: 1–10000	method = GET, POST және pagination = page, offset болғанда көрсетіледі
Бірінші бет нөмірі `first_page`	Баптауға сәйкес Әдепкі: `1` Ауқым: 0–1	method = GET, POST және pagination = page болғанда көрсетіледі
Ең көп бет саны `max_pages`	Баптауға сәйкес Әдепкі: `100` Ауқым: 1–10000	method = GET, POST және pagination = next_link, link_header, page, offset болғанда көрсетіледі
Жолдарды жіберу тәсілі `send_mode`	Баптауға сәйкес Әдепкі: `row`	Қабылдаушылар үшін. JSON: жол — «баған: мән» нысаны, топтама — нысандар массиві. XML: жол элементі, топтама түбірлік элемент ішінде орналасады. Пішін деректері: тек жеке сұраулар. CSV: тақырып жолынан кейін мәндер жолдары. `row` — Әр жолға бір сұрау `batch` — Топтамалар — бір сұрауда бірнеше жол method = POST, PUT, PATCH болғанда көрсетіледі
Топтамадағы жолдар саны `batch_size`	Баптауға сәйкес Әдепкі: `100` Ауқым: 1–10000	method = POST, PUT, PATCH және send_mode = batch болғанда көрсетіледі
JSON топтама денесіндегі массив кілті (міндетті емес) `batch_key`	Баптауға сәйкес	method = POST, PUT, PATCH, send_mode = batch және request_format = json болғанда көрсетіледі
XML топтамасының түбірлік элементі `xml_root`	Баптауға сәйкес Әдепкі: `records`	method = POST, PUT, PATCH, send_mode = batch және request_format = xml болғанда көрсетіледі
Құпиясөз, токен, кілт немесе клиент құпиясы `secret`	Бөлек қорғалған өріс	Сақталғаннан кейін құпия көрсетілмейді. Қолданыстағы қосылымда бос өріс ағымдағы құпияны сақтайды.

Баптау және тексеру

Қосылым жасап, түсінікті атау беріңіз.
Міндетті өрістер мен бөлек құпия өрісін толтырыңыз.
«Тексеру» әрекетін орындап, диагностиканы оқыңыз.
Қосылымды сақтап, ағынның тиісті блогында таңдаңыз.

Сәтті тексеру қажетті нысанға қатынауды және нақты жазу режимін тексеруді алмастырмайды.

Ағында пайдалану

Сервер мен тіркелгі баптаулары қосылымда сақталады. Нақты нысан, өрістер және ағын әрекеті блокта анықталады. Деректермен жұмыс ережелеріне өту →