API docs by Redocly

Service Desk API (1.1.0)

Download OpenAPI specification:

API Team: api-team@example.edu URL: https://github.com/MaximBytecamp/api-standard-template License: MIT

Учебный стандартизированный REST API

Учебный API системы регистрации обращений в службу поддержки.

  • Контракт описан правилами из docs/API_STYLE_GUIDE.md, источники правил — docs/STANDARDS.md.
  • Ошибки возвращаются в формате Problem Details (RFC 9457), application/problem+json.
  • Операции записи требуют Bearer token: demo-token — запись, viewer-token — только чтение.
  • Мажорная версия API указана в пути: /api/v1.
  • Каждый ответ содержит X-Request-Id. Обращение отдаётся с ETag, изменение принимает If-Match.

Tickets

Обращения в службу поддержки: создание, просмотр, изменение и удаление

Получить список обращений

Возвращает страницу обращений. Размер страницы ограничен параметром limit.

query Parameters
TicketStatus (string) or Status (null) (Status)

Показать только обращения с этим статусом

limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Сколько обращений вернуть, от 1 до 100

offset
integer (Offset) >= 0
Default: 0

Сколько обращений пропустить от начала выборки

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Создать обращение

Регистрирует новое обращение со статусом open. Идентификатор формирует сервер. Повтор запроса с тем же Idempotency-Key и тем же телом не создаёт второе обращение.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)

Уникальный ключ запроса. Повтор с тем же ключом и телом вернёт первый результат

Request Body schema: application/json
required
title
required
string (Title) [ 3 .. 120 ] characters

Короткая суть обращения

description
string (Description) <= 2000 characters
Default: ""

Что делали и что увидели

Responses

Request samples

Content type
application/json
{
  • "description": "Ошибка подключения после обновления клиента",
  • "title": "Не работает VPN"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-09-15T17:30:00Z",
  • "description": "Ошибка подключения после обновления клиента",
  • "id": "8d45c3e2-7f1a-4c55-9a39-2b1f0e6d4a10",
  • "status": "open",
  • "title": "Не работает VPN",
  • "updated_at": "2026-09-15T17:30:00Z"
}

Получить открытые обращения (устарело) Deprecated

Устарело с 16.09.2026, будет отключено 01.03.2027. Используйте GET /api/v1/tickets?status=open. Ответ содержит заголовки Deprecation (RFC 9745) и Sunset (RFC 8594).

query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Сколько обращений вернуть, от 1 до 100

offset
integer (Offset) >= 0
Default: 0

Сколько обращений пропустить от начала выборки

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Получить обращение

Возвращает одно обращение. Если If-None-Match совпадает с текущим ETag, сервер отвечает 304 без тела.

path Parameters
ticket_id
required
string <uuid> (Ticket Id)
header Parameters
If-None-Match (string) or If-None-Match (null) (If-None-Match)

ETag, полученный ранее

Responses

Response samples

Content type
application/json
{
  • "created_at": "2026-09-15T17:30:00Z",
  • "description": "Ошибка подключения после обновления клиента",
  • "id": "8d45c3e2-7f1a-4c55-9a39-2b1f0e6d4a10",
  • "status": "open",
  • "title": "Не работает VPN",
  • "updated_at": "2026-09-15T17:30:00Z"
}

Изменить обращение

Меняет только переданные поля. Если передан If-Match и обращение за это время изменилось, сервер отвечает 412 и ничего не меняет.

Authorizations:
BearerAuth
path Parameters
ticket_id
required
string <uuid> (Ticket Id)
header Parameters
If-Match (string) or If-Match (null) (If-Match)

ETag версии, которую клиент видел перед изменением

Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Description (string) or Description (null) (Description)
TicketStatus (string) or null

Responses

Request samples

Content type
application/json
{
  • "status": "closed"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-09-15T17:30:00Z",
  • "description": "Ошибка подключения после обновления клиента",
  • "id": "8d45c3e2-7f1a-4c55-9a39-2b1f0e6d4a10",
  • "status": "open",
  • "title": "Не работает VPN",
  • "updated_at": "2026-09-15T17:30:00Z"
}

Удалить обращение

Удаляет обращение. Успешный ответ не содержит тела.

Authorizations:
BearerAuth
path Parameters
ticket_id
required
string <uuid> (Ticket Id)

Responses

Response samples

Content type
application/problem+json
{}