айва logo айва

API DOCS

Документация
API

Публичные JSON API для блога и портфолио. Страница ниже показывает, какие параметры поддерживаются, как устроен ответ и что именно приходит в интеграцию.

Общие правила

JSON API доступно только по секретному ключу. Используйте его во внешних проектах, мобильных клиентах и внутренних интеграциях.

Формат

JSON, UTF-8

Авторизация

Требуется секретный ключ

Методы

GET, OPTIONS

CORS

Разрешен: Access-Control-Allow-Origin: *

Передавайте ключ либо в заголовке `X-API-Key`, либо в заголовке `Authorization: Bearer <key>`.

Во всех ответах есть поле `ok`, чтобы быстро проверять успешность запроса.

Параметр `lang` поддерживает `ru`, `en`, `zh`. Если передан другой язык, API вернет `ru`.

`limit` ограничен диапазоном от `1` до `100`.

`offset` используется только для списков и нужен для постраничной загрузки.

Для `OPTIONS` endpoint отвечает кодом `204`, для неподдерживаемого метода возвращается `405`.

Авторизация

GET-запросы к API без валидного ключа возвращают `401 Unauthorized`. `OPTIONS` остается открытым для CORS preflight.

Вариант 1: X-API-Key

X-API-Key: <your-secret-key>

Вариант 2: Authorization Bearer

Authorization: Bearer <your-secret-key>

Blog API

Отдает список постов блога или один пост по `slug`.

Endpoint

https://www.aiwa.company/api/v1/blog/

Параметры

Поле Тип Обязателен Описание
lang string Нет ru, en, zh. Defaults to ru.
slug string Нет Return one post by slug.
limit integer Нет Number of posts in list mode. Default 20, max 100.
offset integer Нет List offset for pagination.

Примеры запросов

curl -H "X-API-Key: <your-secret-key>" "https://www.aiwa.company/api/v1/blog/?lang=ru&limit=5"
curl -H "Authorization: Bearer <your-secret-key>" "https://www.aiwa.company/api/v1/blog/?lang=ru&slug=how-to-build-fast-websites"

Что приходит в ответе

Поле Тип Описание
ok boolean Флаг успешного ответа.
resource string Тип ресурса: `blog` или `portfolio`.
lang string Язык локализации ответа.
count integer Количество элементов в `items` текущего ответа.
items array Массив объектов ресурса.

Portfolio API

Отдает список кейсов портфолио или один кейс по `slug`.

Портфолио всегда возвращается в порядке `sort_order ASC`. Это тот же порядок, который виден на публичной странице портфолио: элемент выше в админке приходит раньше в API.

Endpoint

https://www.aiwa.company/api/v1/portfolio/

Параметры

Поле Тип Обязателен Описание
lang string Нет ru, en, zh. Defaults to ru.
slug string Нет Return one case by slug.
category string Нет Return only cases from the specified category.
limit integer Нет Number of cases in list mode. Default 20, max 100.
offset integer Нет List offset for pagination.

Примеры запросов

curl -H "X-API-Key: <your-secret-key>" "https://www.aiwa.company/api/v1/portfolio/?lang=ru&limit=6"
curl -H "X-API-Key: <your-secret-key>" "https://www.aiwa.company/api/v1/portfolio/?lang=ru&category=Web&limit=6"
curl -H "Authorization: Bearer <your-secret-key>" "https://www.aiwa.company/api/v1/portfolio/?lang=ru&slug=aiwa-corporate-website"

Что приходит в ответе

Поле Тип Описание
ok boolean Флаг успешного ответа.
resource string Тип ресурса: `blog` или `portfolio`.
lang string Язык локализации ответа.
count integer Количество элементов в `items` текущего ответа.
items array Массив объектов ресурса.
total integer Полное количество кейсов после фильтрации, до применения `limit` и `offset`.
limit integer|null Текущее значение лимита. Для запроса по `slug` возвращается `null`.
offset integer|null Текущее смещение списка. Для запроса по `slug` возвращается `null`.
filters object Примененные фильтры: `slug`, `category`.
order object Информация о сортировке. Сейчас это `sort_order` по возрастанию.

Основные поля элемента портфолио

Поле Тип Описание
id string ID кейса.
slug string Уникальный slug для поиска кейса по API и построения ссылки.
sort_order integer Позиция кейса в общем порядке портфолио. Чем меньше число, тем выше кейс.
category string Категория кейса.
website_url string Ссылка на сайт проекта, если она заполнена.
cover_image_url string Обложка кейса.
tech_stack string Технологический стек.
title string Локализованный заголовок кейса.
summary string Короткое описание кейса.
content_html string HTML-контент кейса.
date string Дата создания в локализованном формате.
seo_title string SEO title.
seo_description string SEO description.
seo_keywords string SEO keywords.

JSON

{
  "ok": true,
  "resource": "portfolio",
  "lang": "ru",
  "count": 2,
  "total": 14,
  "limit": 2,
  "offset": 0,
  "filters": {
    "slug": null,
    "category": "Web"
  },
  "order": {
    "field": "sort_order",
    "direction": "asc",
    "note": "Items are returned in the same order as the public portfolio page."
  },
  "items": [
    {
      "id": "17",
      "slug": "aiwa-corporate-website",
      "sort_order": 1,
      "category": "Web",
      "title": "AIWA Corporate Website"
    },
    {
      "id": "21",
      "slug": "studio-redesign",
      "sort_order": 2,
      "category": "Web",
      "title": "Studio Redesign"
    }
  ]
}

Коды ответов

Поле Описание
401 Секретный ключ отсутствует или неверен.
200 Успешный JSON-ответ.
204 Ответ на `OPTIONS` без тела.
405 Метод не поддерживается.