Справочник API

Полный справочник REST API для Mockarty. Базовый URL: http://localhost:5770 (по умолчанию).

Все тела запросов/ответов используют Content-Type: application/json, если не указано иное.

URL-адреса в примерах: Все примеры используют localhost:5770 как адрес по умолчанию. Если ваш Mockarty развёрнут на удалённом сервере (например, https://mockarty.company.com или http://192.168.1.50:5770), замените localhost:5770 на реальный адрес. SDK принимают базовый URL в конструкторе клиента, так что его достаточно указать один раз. Подробнее — в Быстром старте.

Совет: Все примеры ниже доступны на нескольких языках. Используйте вкладки для переключения между cURL, CLI и SDK-клиентами. Подробнее об установке и использовании SDK — в Руководстве по SDK. Документация CLI — в Руководстве по CLI.

Hello World: Первый мок за 30 секунд

Создайте мок и вызовите его – две команды, никакой конфигурации:

cURL

# 1. Создаём мок
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hello-world",
    "namespace": "sandbox",
    "http": {
      "route": "/api/greeting",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "message": "Hello, World!",
        "timestamp": "$.fake.DateTimeISO"
      }
    }
  }'

# 2. Вызываем мок (namespace — часть URL)
curl http://localhost:5770/stubs/sandbox/api/greeting
# Возвращает: {"message": "Hello, World!", "timestamp": "2026-03-22T10:30:00Z"}

CLI

# Установка: https://github.com/mockarty/releases

# 1. Создаём мок (пространство имён по умолчанию "sandbox")
mockarty-cli mock create \
  --id hello-world \
  --route /api/greeting \
  --method GET \
  --status 200 \
  --body '{"message": "Hello, World!", "timestamp": "$.fake.DateTimeISO"}'

# 2. Вызываем мок — namespace всегда часть URL
curl http://localhost:5770/stubs/sandbox/api/greeting

Go

// go get github.com/mockarty/mockarty-go

package main

import (
	"context"
	"fmt"
	"github.com/mockarty/mockarty-go"
)

func main() {
	// Пространство имён по умолчанию "sandbox"
	client := mockarty.NewClient("http://localhost:5770",
		mockarty.WithAPIKey("mk_YOUR_TOKEN"),
	)

	mock := mockarty.NewMockBuilder().
		ID("hello-world").
		HTTP(func(h *mockarty.HTTPBuilder) {
			h.Route("/api/greeting").Method("GET")
		}).
		Response(func(r *mockarty.ResponseBuilder) {
			r.Status(200).JSONBody(map[string]any{
				"message":   "Hello, World!",
				"timestamp": "$.fake.DateTimeISO",
			})
		}).
		Build()

	resp, err := client.Mocks().Create(context.Background(), mock)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Создан: %s (перезаписан: %v)\n", resp.Mock.ID, resp.Overwritten)
}

Python

# pip install mockarty

from mockarty import MockartyClient
from mockarty.builders import MockBuilder

# Пространство имён по умолчанию "sandbox"
client = MockartyClient(
    base_url="http://localhost:5770",
    api_key="mk_YOUR_TOKEN",
)

mock = (
    MockBuilder.http("/api/greeting", "GET")
    .id("hello-world")
    .respond(200, body={
        "message": "Hello, World!",
        "timestamp": "$.fake.DateTimeISO",
    })
    .build()
)

result = client.mocks.create(mock)
print(f"Создан: {result.mock.id}, перезаписан: {result.overwritten}")

Java

// Gradle: implementation "ru.mockarty:mockarty-java:1.0.0"

import ru.mockarty.MockartyClient;
import ru.mockarty.builder.MockBuilder;
import ru.mockarty.model.Mock;
import ru.mockarty.model.SaveMockResponse;
import java.util.Map;

// Пространство имён по умолчанию "sandbox"
try (MockartyClient client = MockartyClient.builder()
        .baseUrl("http://localhost:5770")
        .apiKey("mk_YOUR_TOKEN")
        .build()) {

    Mock mock = MockBuilder.http("/api/greeting", "GET")
        .id("hello-world")
        .respond(200, Map.of(
            "message", "Hello, World!",
            "timestamp", "$.fake.DateTimeISO"
        ))
        .build();

    SaveMockResponse resp = client.mocks().create(mock);
    System.out.println("Создан: " + resp.getMock().getId());
}

Kotlin

// Gradle: implementation("ru.mockarty:mockarty-kotlin:1.0.0")

import ru.mockarty.MockartyClient
import ru.mockarty.dsl.createMock

// Пространство имён по умолчанию "sandbox"
val client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .build()

client.createMock {
    id = "hello-world"
    http {
        route = "/api/greeting"
        method = "GET"
    }
    respond {
        statusCode = 200
        body = mapOf(
            "message" to "Hello, World!",
            "timestamp" to "$.fake.DateTimeISO"
        )
    }
}

Как это работает: Вы определяете мок через POST /api/v1/mocks, затем Mockarty обслуживает его по адресу /stubs/<ваш-маршрут>. Префикс /stubs указывает Mockarty разрешить мок, а не обращаться к API управления. Динамические значения вроде $.fake.DateTimeISO подставляются в момент формирования ответа.

Содержание

1. Аутентификация
2. API управления моками (публичный)
3. API пространств имён
4. API хранилищ
5. API шаблонов
6. Руководство по CI/CD интеграции
7. API тестирования API
8. API нагрузочного тестирования
9. API фаззинга
10. API рекордера
11. API контрактного тестирования
12. API Chaos Engineering
13. API администрирования
14. Утилиты
15. Прокси-эндпоинты протоколов

1. Аутентификация

Mockarty использует два механизма аутентификации: API-токены для программного доступа и сессионные куки для Web UI.

API-токены

Создавайте токены в Web UI (Настройки > API-токены) или через POST /api/v1/auth/tokens.

Передавайте токен в запросах через заголовок:

cURL

# Заголовок X-API-Key (пространство "sandbox" по умолчанию)
curl -H "X-API-Key: mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

# Заголовок Authorization: Bearer
curl -H "Authorization: Bearer mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

CLI

# Настройка токена глобально (сохраняется в ~/.mockarty-cli/config.yaml)
mockarty-cli config set token mk_YOUR_TOKEN
mockarty-cli config set namespace sandbox

# Или передать для конкретной команды
mockarty-cli mock list --token mk_YOUR_TOKEN

Go

// Токен задаётся через опцию WithAPIKey; пространство по умолчанию "sandbox"
client := mockarty.NewClient("http://localhost:5770",
    mockarty.WithAPIKey("mk_YOUR_TOKEN"),
    mockarty.WithNamespace("sandbox"), // необязательно, "sandbox" по умолчанию
)

Python

# Токен задаётся через параметр api_key; пространство по умолчанию "sandbox"
client = MockartyClient(
    base_url="http://localhost:5770",
    api_key="mk_YOUR_TOKEN",
    namespace="sandbox",  # необязательно, "sandbox" по умолчанию
)

Java

// Токен задаётся через apiKey; пространство по умолчанию "sandbox"
MockartyClient client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .build();

Kotlin

// Токен задаётся через apiKey; пространство по умолчанию "sandbox"
val client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .build()

Сессионная аутентификация

Для Web UI и доступа через браузер:

# Вход (возвращает сессионную куку)
curl -c cookies.txt -X POST http://localhost:5770/api/v1/auth/login \
  -d '{"username": "admin", "password": "secret"}'

# Использование сессионной куки
curl -b cookies.txt http://localhost:5770/api/v1/mocks

Эндпоинты аутентификации

Ограничение частоты запросов

Запросы к API ограничены в зависимости от лицензии. Лимиты применяются отдельно для каждого API-ключа.

2. API управления моками (публичный)

Эндпоинты для управления определениями моков. Доступны на корневом сервере (порт 5770). Требуют аутентификации с правом read или write.

Создание/обновление мока

POST /api/v1/mocks | Авторизация: пользователь (write)

Создаёт новый мок или перезаписывает существующий (по id).

cURL

curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "get-user",
    "namespace": "sandbox",
    "http": {
      "route": "/api/users/list",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "id": "$.fake.UUID",
        "name": "$.fake.FirstName",
        "email": "$.fake.Email"
      }
    }
  }'

CLI

# Пространство имён по умолчанию "sandbox"
mockarty-cli mock create \
  --id get-user \
  --route /api/users/list \
  --method GET \
  --status 200 \
  --body '{"id": "$.fake.UUID", "name": "$.fake.FirstName", "email": "$.fake.Email"}'

Go

mock := mockarty.NewMockBuilder().
    ID("get-user").
    Namespace("sandbox"). // необязательно, "sandbox" по умолчанию
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/list").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "id":    "$.fake.UUID",
            "name":  "$.fake.FirstName",
            "email": "$.fake.Email",
        })
    }).
    Build()

resp, err := client.Mocks().Create(context.Background(), mock)

Python

mock = (
    MockBuilder.http("/api/users/list", "GET")
    .id("get-user")
    .namespace("sandbox")  # необязательно, "sandbox" по умолчанию
    .respond(200, body={
        "id": "$.fake.UUID",
        "name": "$.fake.FirstName",
        "email": "$.fake.Email",
    })
    .build()
)

result = client.mocks.create(mock)

Java

Mock mock = MockBuilder.http("/api/users/list", "GET")
    .id("get-user")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .respond(200, Map.of(
        "id", "$.fake.UUID",
        "name", "$.fake.FirstName",
        "email", "$.fake.Email"
    ))
    .build();

SaveMockResponse resp = client.mocks().create(mock);

Kotlin

client.createMock {
    id = "get-user"
    namespace = "sandbox"  // необязательно, "sandbox" по умолчанию
    http {
        route = "/api/users/list"
        method = "GET"
    }
    respond {
        statusCode = 200
        body = mapOf(
            "id" to "$.fake.UUID",
            "name" to "$.fake.FirstName",
            "email" to "$.fake.Email"
        )
    }
}

Ответ:

{
  "overwritten": false,
  "mock": {
    "id": "get-user",
    "namespace": "default",
    "createdAt": 1704096000000,
    "useCounter": 0
  }
}

Полная структура мока (все поля необязательны, кроме id):

Структура условия (Condition)

Что такое условия? Условия позволяют возвращать разные ответы мока в зависимости от входящего запроса. Без условий мок соответствует любому запросу к его маршруту. С условиями Mockarty анализирует тело запроса, заголовки или параметры и выбирает мок только если все условия выполнены. Это полезно, когда несколько моков имеют один маршрут, но должны отвечать по-разному в зависимости от содержимого запроса (например, вернуть ошибку, когда $.body.status равен "invalid").

Массив conditions внутри конфигурационных объектов http, grpc и mcp управляет выбором мока. Каждое условие — объект со следующими полями:

Действия проверки (Assert actions):

Примечание: Устаревший псевдоним match также принимается и работает идентично matches.

Пример с расширенными полями условий:

{
  "id": "base64-body-mock",
  "http": {
    "route": "/api/validate",
    "httpMethod": "POST",
    "conditions": [
      {
        "path": "$.body.encodedData",
        "assertAction": "contains",
        "value": "expected-content",
        "decode": "base64"
      },
      {
        "path": "$.body.items",
        "assertAction": "equals",
        "value": ["b", "a", "c"],
        "sortArray": true
      },
      {
        "path": "$.body.payload",
        "assertAction": "equals",
        "valueFromFile": "/templates/expected-payload.json"
      }
    ]
  },
  "response": {
    "statusCode": 200,
    "payload": {"status": "validated"}
  }
}

Примечание: decode, sortArray и valueFromFile — поля только для API, они не доступны в визуальном конструкторе Web UI.

Получение мока

GET /api/v1/mocks/:id | Авторизация: пользователь (read)

cURL

curl -H "X-API-Key: mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks/get-user

CLI

mockarty-cli mock get get-user

Go

mock, err := client.Mocks().Get(context.Background(), "get-user")

Python

mock = client.mocks.get("get-user")

Java

Mock mock = client.mocks().get("get-user");

Kotlin

val mock = client.mocks().get("get-user")

Список моков

GET /api/v1/mocks | Авторизация: пользователь (read)

cURL

# Пространство "sandbox" по умолчанию
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/mocks?namespace=sandbox&limit=10"

CLI

mockarty-cli mock list --namespace sandbox --limit 10

Go

page, err := client.Mocks().List(context.Background(), &mockarty.ListMocksOptions{
    Namespace: "sandbox", // необязательно, "sandbox" по умолчанию
    Limit:     10,
})
for _, m := range page.Items {
    fmt.Println(m.ID)
}

Python

page = client.mocks.list(namespace="sandbox", limit=10)
for mock in page.items:
    print(mock.id)

Java

Page<Mock> page = client.mocks().list("sandbox", null, null, 0, 10);
for (Mock m : page.getItems()) {
    System.out.println(m.getId());
}

Kotlin

val page = client.mocks().list("sandbox", null, null, 0, 10)
page.items.forEach { println(it.id) }

Удаление мока (мягкое)

DELETE /api/v1/mocks/:id | Авторизация: пользователь (delete)

cURL

curl -X DELETE -H "X-API-Key: mk_YOUR_TOKEN" \
  http://localhost:5770/api/v1/mocks/get-user

CLI

mockarty-cli mock delete get-user

Go

err := client.Mocks().Delete(context.Background(), "get-user")

Python

client.mocks.delete("get-user")

Java

client.mocks().delete("get-user");

Kotlin

client.mocks().delete("get-user")

Восстановление мока

GET /api/v1/mocks/:id | Авторизация: пользователь (write)

Полное удаление мока

DELETE /api/v1/mocks/:id/purge | Авторизация: пользователь (delete)

Журналы запросов мока

GET /api/v1/mocks/:id/logs | Авторизация: пользователь (read)

Возвращает историю запросов к моку.

{
  "id": "get-user",
  "requests": [
    {
      "calledAt": "2024-01-01T10:05:00Z",
      "req": {
        "header": {},
        "body": {},
        "queryParam": {},
        "url": "/stubs/api/users/123"
      }
    }
  ]
}

Цепочки моков

Пакетное создание

POST /api/v1/mocks/batch | Авторизация: пользователь (write)

Создание нескольких моков за один запрос.

cURL

curl -X POST http://localhost:5770/api/v1/mocks/batch \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"id": "mock-1", "namespace": "sandbox", "http": {"route": "/api/a", "httpMethod": "GET"}, "response": {"statusCode": 200}},
    {"id": "mock-2", "namespace": "sandbox", "http": {"route": "/api/b", "httpMethod": "GET"}, "response": {"statusCode": 200}}
  ]'

CLI

# Пакетное создание из JSON-файла (пространство по умолчанию "sandbox")
mockarty-cli mock create --file mocks.json --batch

Go

mocks := []*mockarty.Mock{
    mockarty.NewMockBuilder().ID("mock-1").
        HTTP(func(h *mockarty.HTTPBuilder) { h.Route("/api/a").Method("GET") }).
        Response(func(r *mockarty.ResponseBuilder) { r.Status(200) }).
        Build(),
    mockarty.NewMockBuilder().ID("mock-2").
        HTTP(func(h *mockarty.HTTPBuilder) { h.Route("/api/b").Method("GET") }).
        Response(func(r *mockarty.ResponseBuilder) { r.Status(200) }).
        Build(),
}

err := client.Mocks().BatchCreate(context.Background(), mocks)

Python

mocks = [
    MockBuilder.http("/api/a", "GET").id("mock-1").respond(200).build(),
    MockBuilder.http("/api/b", "GET").id("mock-2").respond(200).build(),
]

results = client.mocks.batch_create(mocks)

Java

// В Java SDK нет отдельного метода batchCreate;
// используйте цикл для создания каждого мока по отдельности
Mock mock1 = MockBuilder.http("/api/a", "GET").id("mock-1").respond(200).build();
Mock mock2 = MockBuilder.http("/api/b", "GET").id("mock-2").respond(200).build();

client.mocks().create(mock1);
client.mocks().create(mock2);

Частичное обновление (Patch)

PATCH /api/v1/mocks/:id | Авторизация: пользователь (write)

Частичное обновление мока (переданные поля объединяются с существующим моком).

cURL

curl -X PATCH http://localhost:5770/api/v1/mocks/get-user \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -d '{"response": {"statusCode": 201}}'

CLI

# CLI не предоставляет отдельной команды patch.
# Экспортируйте мок, отредактируйте его локально и примените полное определение —
# сервер обновит существующий мок по id.
mockarty-cli mock get get-user -o json > mock.json
# отредактируйте mock.json (например, измените response.statusCode на 201)
mockarty-cli mock create -f mock.json

Go

updated, err := client.Mocks().Patch(context.Background(), "get-user", map[string]any{
    "response": map[string]any{"statusCode": 201},
})

Python

updated = client.mocks.patch("get-user", {"response": {"statusCode": 201}})

Java

Mock updated = client.mocks().patchMock("get-user", Map.of(
    "response", Map.of("statusCode", 201)
));

История версий мока

Предпросмотр разрешения мока

GET /api/v1/mocks/preview | Авторизация: пользователь (read)

Предпросмотр того, какой мок будет разрешён для указанного маршрута/метода без фактического вызова stub-эндпоинта.

Пакетные операции (UI API)

Теги

Папки моков

Организация моков в папки для удобного управления.

Неопределённые запросы

Перехваченные запросы, не совпавшие ни с одним моком.

3. API пространств имён

Пример копирования моков:

cURL

curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  http://localhost:5770/api/v1/mocks/copy-to-namespace \
  -d '{
    "sourceNamespace": "staging",
    "targetNamespace": "production",
    "mockIds": ["mock-1", "mock-2"]
  }'

CLI

mockarty-cli namespace copy \
  --from staging --to production \
  --ids mock-1,mock-2

Go

err := client.Mocks().CopyToNamespace(context.Background(),
    []string{"mock-1", "mock-2"}, "production",
)

Python

client.mocks.copy_to_namespace(
    ids=["mock-1", "mock-2"],
    target_namespace="production",
)

Java

client.mocks().copyToNamespace(
    List.of("mock-1", "mock-2"),
    "production"
);

4. API хранилищ

Три типа хранилищ для моков с состоянием. Подробнее в Системе хранилищ.

Глобальное хранилище

Каждый POST-запрос добавляет одну пару ключ-значение. Для добавления нескольких ключей выполните отдельные запросы.

cURL

# Установить пару ключ-значение (один за запрос)
curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global" \
  -d '{"key": "totalUsers", "value": "100", "namespace": "sandbox"}'

curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global" \
  -d '{"key": "serviceName", "value": "auth", "namespace": "sandbox"}'

# Прочитать хранилище
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global?namespace=sandbox"

# Удалить ключ (ключ в URL-пути)
curl -X DELETE -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global/totalUsers?namespace=sandbox"

CLI

# Установить значение (пространство по умолчанию "sandbox")
mockarty-cli store global set totalUsers 100
mockarty-cli store global set serviceName auth

# Прочитать хранилище
mockarty-cli store global get

# Удалить ключ
mockarty-cli store global delete totalUsers

Go

// Установить значения (используется пространство клиента по умолчанию "sandbox")
err := client.Stores().GlobalSet(context.Background(), "totalUsers", 100)
err = client.Stores().GlobalSet(context.Background(), "serviceName", "auth")

// Прочитать хранилище
store, err := client.Stores().GlobalGet(context.Background())
fmt.Println(store) // map[totalUsers:100 serviceName:auth ...]

// Удалить ключ
err = client.Stores().GlobalDelete(context.Background(), "totalUsers")

Python

# Установить значения (используется пространство клиента по умолчанию "sandbox")
client.stores.global_set("totalUsers", 100)
client.stores.global_set("serviceName", "auth")

# Или установить несколько значений за раз
client.stores.global_set_many({"totalUsers": 100, "serviceName": "auth"})

# Прочитать хранилище
store = client.stores.global_get()
print(store)  # {"totalUsers": 100, "serviceName": "auth"}

# Удалить ключи
client.stores.global_delete("totalUsers")

Java

// Установить значения (используется пространство клиента по умолчанию "sandbox")
client.stores().globalSet("totalUsers", 100);
client.stores().globalSet("serviceName", "auth");

// Прочитать хранилище
Map<String, Object> store = client.stores().globalGet();
System.out.println(store);

// Удалить ключ
client.stores().globalDelete("totalUsers");

Хранилище цепочки

5. API шаблонов

Загрузка шаблонов ответов для использования в моках через payloadTemplatePath.

Временное хранилище файлов

Временная загрузка файлов для использования в интерфейсе чата с агентом. Файлы автоматически удаляются через 30 минут.

Генерация из OpenAPI (сокращённая форма)

6. Руководство по CI/CD интеграции

Mockarty предоставляет полное API-покрытие для автоматизации CI/CD. Все примеры используют аутентификацию по API-токену.

6.1 Запуск API-тестов из CI

cURL

TOKEN="mk_YOUR_TOKEN"
BASE="http://localhost:5770/ui/api"

# 1. Создание коллекции
COLLECTION_ID=$(curl -s -X POST "$BASE/api-tester/collections" \
  -H "X-API-Key: $TOKEN" \
  -d '{"name": "CI Tests", "description": "Automated test suite"}' | jq -r '.id')

# 2. Добавление запроса с тестовым скриптом
curl -X POST "$BASE/api-tester/collections/$COLLECTION_ID/requests" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "Get Users",
    "method": "GET",
    "url": "http://localhost:5770/stubs/sandbox/api/users",
    "testScript": "mk.test(\"Status is 200\", function() { mk.response.to.have.status(200); });"
  }'

# 3. Выполнение коллекции (запускает все запросы + тестовые скрипты)
RUN_ID=$(curl -s -X POST "$BASE/api-tester/collections/$COLLECTION_ID/execute" \
  -H "X-API-Key: $TOKEN" \
  -d '{}' | jq -r '.runId')

# 4. Проверка результатов
curl -s "$BASE/api-tester/test-runs/$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.status, .summary'

CLI

# Запуск существующей коллекции по имени или ID
mockarty-cli run collection "CI Tests" --wait --format json

# Запуск с экспортом JUnit-отчёта для CI
mockarty-cli run collection "CI Tests" --wait --junit-report results.xml

Go

// Создание коллекции и выполнение
col, err := client.Collections().Create(context.Background(), &mockarty.Collection{
    Name:        "CI Tests",
    Description: "Automated test suite",
})

// Выполнение коллекции
run, err := client.Collections().Execute(context.Background(), col.ID)
fmt.Printf("Run ID: %s, Status: %s\n", run.ID, run.Status)

Python

# Создание коллекции и выполнение
col = client.collections.create({
    "name": "CI Tests",
    "description": "Automated test suite",
})

# Выполнение коллекции
run = client.collections.execute(col.id)
print(f"Run ID: {run.id}, Status: {run.status}")

Java

// Создание коллекции и выполнение
Map<String, Object> col = client.collections().create(Map.of(
    "name", "CI Tests",
    "description", "Automated test suite"
));

String collectionId = (String) col.get("id");
Map<String, Object> run = client.collections().execute(collectionId, Map.of());
System.out.println("Run ID: " + run.get("runId"));

6.2 Запуск нагрузочных тестов из CI

cURL

# 1. Создание конфигурации нагрузочного теста (привязана к коллекции)
CONFIG_ID=$(curl -s -X POST "$BASE/perf-configs" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "Load Test",
    "collectionId": "'$COLLECTION_ID'",
    "vus": 10,
    "duration": "30s"
  }' | jq -r '.id')

# 2. Запуск нагрузочного теста с инлайн-скриптом
curl -X POST "$BASE/perf/run" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "script": "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options": {"vus": 10, "duration": "30s"}
  }'

# 3. Проверка результатов
curl -s "$BASE/perf-results" -H "X-API-Key: $TOKEN" | jq '.[0]'

CLI

# Запуск нагрузочного теста из существующей конфигурации
mockarty-cli perf run --config "Load Test" --wait

# Запуск с инлайн-параметрами
mockarty-cli perf run --vus 10 --duration 30s \
  --url http://localhost:5770/stubs/sandbox/api/users

Go

// Запуск нагрузочного теста
result, err := client.Perf().Run(context.Background(), &mockarty.PerfRunRequest{
    Script:  `import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }`,
    Options: map[string]any{"vus": 10, "duration": "30s"},
})

// Список результатов
results, err := client.Perf().ListResults(context.Background())

Python

# Запуск нагрузочного теста
result = client.perf.run({
    "script": 'import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }',
    "options": {"vus": 10, "duration": "30s"},
})

# Список результатов
results = client.perf.list_results()

Java

// Запуск нагрузочного теста
Map<String, Object> result = client.perf().run(Map.of(
    "script", "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options", Map.of("vus", 10, "duration", "30s")
));

6.3 Запуск фаззинга из CI

cURL

# 1. Создание конфигурации фаззинга
CONFIG_ID=$(curl -s -X POST "$BASE/fuzzing/configs" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "API Fuzz",
    "method": "POST",
    "url": "http://target:8080/api/users",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"name\": \"test\"}",
    "payloadCategories": ["sql_injection", "xss"]
  }' | jq -r '.id')

# 2. Запуск фаззинга
RUN_ID=$(curl -s -X POST "$BASE/fuzzing/run" \
  -H "X-API-Key: $TOKEN" \
  -d '{"configId": "'$CONFIG_ID'"}' | jq -r '.id')

# 3. Проверка найденных уязвимостей
curl -s "$BASE/fuzzing/findings?runId=$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.findings'

CLI

# Запуск фаззинга из CLI
mockarty-cli fuzz run --config "API Fuzz" --wait

# Быстрый фаззинг URL
mockarty-cli fuzz quick \
  --url http://target:8080/api/users \
  --method POST \
  --categories sql_injection,xss

Go

// Создание конфигурации и запуск фаззинга
config, err := client.Fuzzing().CreateConfig(context.Background(), &mockarty.FuzzingConfig{
    Name:              "API Fuzz",
    Method:            "POST",
    URL:               "http://target:8080/api/users",
    PayloadCategories: []string{"sql_injection", "xss"},
})

run, err := client.Fuzzing().Run(context.Background(), config.ID)

// Проверка найденных уязвимостей
findings, err := client.Fuzzing().ListFindings(context.Background(), run.ID)

Python

# Создание конфигурации и запуск фаззинга
config = client.fuzzing.create_config({
    "name": "API Fuzz",
    "method": "POST",
    "url": "http://target:8080/api/users",
    "payloadCategories": ["sql_injection", "xss"],
})

run = client.fuzzing.run(config.id)

# Проверка найденных уязвимостей
findings = client.fuzzing.list_findings(run_id=run.id)

Java

// Создание конфигурации и запуск фаззинга
FuzzingConfig config = client.fuzzing().createConfig(Map.of(
    "name", "API Fuzz",
    "method", "POST",
    "url", "http://target:8080/api/users",
    "payloadCategories", List.of("sql_injection", "xss")
));

FuzzingRun run = client.fuzzing().run(config.getId());

6.4 Импорт OpenAPI/Postman/HAR

cURL

# Импорт OpenAPI-спецификации для генерации моков (пространство "sandbox" по умолчанию)
curl -X POST "$BASE/generators/openapi" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@openapi.yaml" \
  -F "namespace=sandbox"

# Импорт коллекции Postman в API Tester
curl -X POST "$BASE/api-tester/import/postman" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@collection.json"

# Импорт HAR-записи
curl -X POST "$BASE/api-tester/import/har" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@recording.har"

# Импорт WSDL для SOAP-моков
curl -X POST "$BASE/api-tester/import/wsdl" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@service.wsdl"

CLI

# Импорт OpenAPI-спецификации (пространство по умолчанию "sandbox")
mockarty-cli generate openapi --file openapi.yaml --namespace sandbox

# Импорт коллекции Postman
mockarty-cli import postman --file collection.json

# Импорт HAR-записи
mockarty-cli import har --file recording.har

Go

// Импорт OpenAPI-спецификации для генерации моков
result, err := client.Generator().OpenAPIGenerate(context.Background(),
    "openapi.yaml", // путь к файлу
    "sandbox",       // пространство имён
)

// Импорт коллекции Postman
importResult, err := client.Imports().Postman(context.Background(), "collection.json")

Python

# Импорт OpenAPI-спецификации для генерации моков
result = client.generator.openapi_generate(
    file_path="openapi.yaml",
    namespace="sandbox",  # необязательно, "sandbox" по умолчанию
)

# Импорт коллекции Postman
import_result = client.imports.postman(file_path="collection.json")

Java

// Импорт OpenAPI-спецификации для генерации моков
GeneratorResponse result = client.generator().openapiGenerate(
    "openapi.yaml", "sandbox"
);

// Импорт коллекции Postman
ImportResult importResult = client.imports().postman("collection.json");

6.5 Настройка моков перед тестами

cURL

# Создание моков для тестового окружения (пространство "sandbox" по умолчанию)
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "id": "ci-user-service",
    "namespace": "sandbox",
    "http": {"route": "/api/users/list", "httpMethod": "GET"},
    "response": {
      "statusCode": 200,
      "payload": {"id": "$.fake.UUID", "name": "Test User"}
    }
  }'

# Проверка, что мок активен
curl http://localhost:5770/stubs/sandbox/api/users/list
# Возвращает: {"id": "a1b2c3d4-...", "name": "Test User"}

# Очистка после тестов
curl -X DELETE -H "X-API-Key: $TOKEN" \
  http://localhost:5770/api/v1/mocks/ci-user-service

CLI

# Создание мока из JSON-файла
mockarty-cli mock create --file ci-mocks.json

# Проверка, что мок активен
curl http://localhost:5770/stubs/sandbox/api/users/list

# Очистка после тестов
mockarty-cli mock delete ci-user-service

Go

// Создание мока для CI
mock := mockarty.NewMockBuilder().
    ID("ci-user-service").
    Namespace("sandbox").
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/list").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "id":   "$.fake.UUID",
            "name": "Test User",
        })
    }).
    Build()

_, err := client.Mocks().Create(context.Background(), mock)

// ... запуск тестов ...

// Очистка
err = client.Mocks().Delete(context.Background(), "ci-user-service")

Python

# Создание мока для CI
mock = (
    MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, body={"id": "$.fake.UUID", "name": "Test User"})
    .build()
)
client.mocks.create(mock)

# ... запуск тестов ...

# Очистка
client.mocks.delete("ci-user-service")

Java

// Создание мока для CI
Mock mock = MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, Map.of("id", "$.fake.UUID", "name", "Test User"))
    .build();

client.mocks().create(mock);

// ... запуск тестов ...

// Очистка
client.mocks().delete("ci-user-service");

7. API тестирования API

Полнофункциональная платформа тестирования API (аналог Postman). Все эндпоинты под /api/v1/ и требуют аутентификации.

Коллекции

Совместный доступ к коллекциям

Запросы

Окружения

Запуски тестов

Режимы единой витрины запусков

Каждая строка из /api/v1/api-tester/test-runs содержит поле mode,
идентифицирующее источник запуска:

Примеры фильтрации:

# Все fuzz-кампании в namespace
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=fuzz"

# Все запуски конкретного chaos-эксперимента
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=chaos&referenceId=$EXPERIMENT_ID"

# Пагинация по функциональным запускам
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=functional&limit=50&offset=100"

Эквиваленты в SDK:

// Go
runs, err := client.TestRuns.ListWithOptions(ctx, mockarty.ListTestRunsOptions{
    Mode:        "fuzz",
    ReferenceID: fuzzConfigID,
    Limit:       50,
})

# Python
runs = client.test_runs.list(mode="chaos", reference_id=experiment_id, limit=50)

// Java
List<TestRun> runs = client.testRuns().listByMode("fuzz", fuzzConfigId, 50, 0);

# CLI
mockarty-cli test-runs list --mode chaos --reference-id "$EXPERIMENT_ID" --limit 50

Скрипты и выполнение

Автономные тесты

Расписания (Cron)

Импорт/экспорт

Вспомогательные эндпоинты протоколов

Kafka Admin

RabbitMQ Admin

8. API нагрузочного тестирования

Встроенное нагрузочное тестирование с k6-совместимыми скриптами. Все эндпоинты под /api/v1/.

Конфигурации нагрузочных тестов

Запуск/остановка тестов

Результаты

Расписания

Задачи раннеров

9. API фаззинга

Фаззинг безопасности со встроенными категориями полезных нагрузок (SQL-инъекции, XSS и др.). Все эндпоинты под /api/v1/fuzzing/.

Сводка и полезные нагрузки

Конфигурации

Импорт

Обнаружение протоколов

Запуски и результаты

аномалии

Расписания

10. API рекордера

Запись HTTP-трафика (на основе прокси). Все эндпоинты под /api/v1/recorder/.

Сессии

Пример начала сессии:

cURL

curl -X POST "$BASE/recorder/start" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "targetUrl": "https://api.example.com",
    "port": 8888,
    "name": "API Recording"
  }'

Go

session, err := client.Recorder().StartRecording(context.Background(), &mockarty.RecorderSession{
    TargetURL: "https://api.example.com",
    Port:      8888,
    Name:      "API Recording",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Сессия запущена: %s\n", session.ID)

Python

session = client.recorder.create({
    "targetUrl": "https://api.example.com",
    "port": 8888,
    "name": "API Recording",
})
print(f"Сессия запущена: {session.id}")

Java

RecorderSession session = client.recorder().start(Map.of(
    "targetUrl", "https://api.example.com",
    "port", 8888,
    "name", "API Recording"
));
System.out.println("Сессия запущена: " + session.getId());

Совет: Те же операции доступны через mockarty-cli recorder ... — справочник команд см. в Руководстве CLI.

Записи

Модификации (перезапись запросов/ответов)

Экспорт

AI-анализ

Конфигурация

WebSocket

11. API контрактного тестирования

Контрактное тестирование проверяет, что ваши моки остаются согласованными со спецификациями реальных API. Поддерживаются: валидация по OpenAPI, потребительские контракты (совместимость с Pact), обнаружение дрейфа API (API drift) и реестр API (внутренний маркетплейс). Все эндпоинты находятся под префиксом /api/v1/contract/.

Валидация моков

Конфигурации и регулярные запуски

Результаты и тренды

аномалии (AI-анализ)

Потребительские контракты (Pact)

Реестр API (внутренний маркетплейс)

Подписки

12. API Chaos Engineering

Kubernetes-нативный chaos engineering для инъекции отказов и проверки отказоустойчивости. Создавайте эксперименты для внесения отказов (убийство подов, сетевые задержки, нагрузка на ресурсы) в ваши кластеры и наблюдайте за поведением сервисов. Все эндпоинты находятся под префиксом /api/v1/chaos/.

Пресеты

Эксперименты

Очередь экспериментов

Инфраструктурные профили

Chaos Operator

Ресурсы Kubernetes

13. API администрирования

Эндпоинты только для администраторов (роль admin). Префикс: /api/v1/admin/.

Управление пользователями

Управление пространствами имён (Админ)

Политики очистки

Настройки LLM/AI

Настройки электронной почты

Управление лицензиями

Провайдеры идентификации

Управление резервными копиями

Мониторинг базы данных

Вебхуки

Аудит и задачи

Телеметрия

MCP Marketplace (Админ)

Интеграционные токены

14. Утилиты

Конвертеры (без аутентификации)

Генерация моков из спецификаций

AI-функции

Уведомления

Задачи агента

Здоровье и мониторинг

Пример ответа health:

{
  "status": "up",
  "releaseId": "1.2.3",
  "checks": {
    "database": {"status": "up"},
    "cache": {"status": "up"}
  }
}

Дашборды

MCP-сервер

Mockarty предоставляет MCP (Model Context Protocol) сервер по адресу GET /mcp/sse. Подключайте AI-инструменты (Claude Desktop, Cursor) для управления моками через естественный язык.

SSE-события

15. Прокси-эндпоинты протоколов

Внутренние эндпоинты, используемые сгенерированными серверами протоколов для разрешения моков. Аутентификация не требуется.

Как работает маршрутизация /stubs/*

Эндпоинт /stubs/* — основной маршрут разрешения моков. Он соответствует любому HTTP-методу и находит подходящий мок на основе маршрута, метода, условий и приоритета. Аутентификация не требуется для вызова стабов — это сделано намеренно, так как тестируемое приложение вызывает эти эндпоинты напрямую.

Маршрутизация по пространствам имён: Namespace извлекается из URL-пути — укажите его первым сегментом после /stubs/. Также можно передать через query-параметр. Если ни то ни другое не указано, Mockarty использует sandbox как fallback.

# Рекомендуется: namespace явно в пути (однозначно, всегда работает)
curl http://localhost:5770/stubs/sandbox/api/users/123
curl http://localhost:5770/stubs/staging/api/users/123

# Альтернатива: namespace через query-параметр
curl "http://localhost:5770/stubs/sandbox/api/users/123?namespace=staging"

# POST с телом (условия сопоставляются с телом запроса)
curl -X POST http://localhost:5770/stubs/sandbox/api/orders \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cust-1", "items": [{"id": "item-1", "price": 29.99}]}'

Префиксы шаблонов в ответах

При построении ответов моков Mockarty поддерживает специальные префиксы для подстановки динамических данных:

Пример с параметрами пути:

cURL

# Создание мока с извлечением параметров пути (пространство "sandbox" по умолчанию)
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "Content-Type: application/json" \
  -d '{
    "id": "get-user-by-id",
    "namespace": "sandbox",
    "http": {
      "route": "/api/users/:id",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "userId": "$.pathParam.id",
        "name": "$.fake.FirstName",
        "namespace": "$.namespace"
      }
    }
  }'

# Вызываем
curl http://localhost:5770/stubs/sandbox/api/users/42
# Возвращает: {"userId": "42", "name": "Alice", "namespace": "sandbox"}

CLI

mockarty-cli mock create \
  --id get-user-by-id \
  --route /api/users/:id \
  --method GET \
  --status 200 \
  --body '{"userId": "$.pathParam.id", "name": "$.fake.FirstName", "namespace": "$.namespace"}'

# Вызываем
curl http://localhost:5770/stubs/sandbox/api/users/42

Go

mock := mockarty.NewMockBuilder().
    ID("get-user-by-id").
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/:id").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "userId":    "$.pathParam.id",
            "name":      "$.fake.FirstName",
            "namespace": "$.namespace",
        })
    }).
    Build()

_, err := client.Mocks().Create(context.Background(), mock)

Python

mock = (
    MockBuilder.http("/api/users/:id", "GET")
    .id("get-user-by-id")
    .respond(200, body={
        "userId": "$.pathParam.id",
        "name": "$.fake.FirstName",
        "namespace": "$.namespace",
    })
    .build()
)

client.mocks.create(mock)

Java

Mock mock = MockBuilder.http("/api/users/:id", "GET")
    .id("get-user-by-id")
    .respond(200, Map.of(
        "userId", "$.pathParam.id",
        "name", "$.fake.FirstName",
        "namespace", "$.namespace"
    ))
    .build();

client.mocks().create(mock);

Связанная документация

• Быстрый старт — запуск за 5 минут
• Справочник Faker-функций — генераторы динамических данных
• Руководство по JsonPath — извлечение и трансформация данных
• Система хранилищ — паттерны Global, Chain и Mock Store
• Нагрузочное тестирование — руководство по нагрузочному тестированию
• Фаззинг — руководство по фаззингу безопасности
• Рекордер — запись HTTP-трафика
• Руководство по Web UI — визуальный интерфейс
• Генератор серверов — генерация автономных серверов протоколов
• Вебхуки и колбэки — уведомления о событиях
• Docker и деплой — руководство по production-деплою