Мониторинг на API

Защо API има нужда от собствен мониторинг

API не е просто страница под /api/. Това е договор. HTTP методът има значение – GET срещу POST променя смисъла. Заглавките носят удостоверяване, преговор за съдържание, idempotent ключове. Тялото на заявката е входът. Кодът на отговора има значение (401 vs 403 vs 422 – всеки казва различна история). Тялото на отговора има структура – JSON пътища, на които разчитат интеграторите. Обикновен uptime check, който само посещава URL с GET, пропуска повечето начини, по които API може да спре да работи: невалиден JSON, който все още връща 200, endpoint за удостоверяване приема невалидни данни, webhook с развален schema на payload-a, endpoint връща 200, но със "status": "error" вътре.

Мониторингът на API решава това, като ти дава контрол над всяка част от заявката и всяка част от валидацията на отговора. Конфигурираш точно такова извикване, каквото правят интеграторите ти – същият метод, същите заглавки, същото тяло, същото удостоверяване – и точно какво значи успех – конкретни кодове, стойности по JSON пътища, прагове за време на отговор, граници за размер.

Конфигуриране на заявката

За всеки API монитор в DiagnoSEO Uptime Monitoring можеш да конфигурираш:

• HTTP метод: GET, POST, PUT, PATCH, DELETE, HEAD. Избери този, който използват твоите интегратори.
• Собствени заглавки: като JSON обект, напр. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Стандарт при тестване на OAuth, JWT, API ключове, negotiation на content.
• Тяло на заявката: произволен string – JSON, XML, form-encoded, plain text. Изпраща се при POST/PUT/PATCH/DELETE.
• Basic auth: потребител и парола, ако endpoint-ът е защитен така.
• Очаквани статус кодове: списък или диапазон. По подразбиране 200-399, но можеш да го ограничиш до един код (напр. точно 201 за endpoint за създаване) или да позволиш конкретни (напр. 200,202,204).

Проверката следва макс. 5 пренасочвания, декодира gzip, анализира Content-Type, за да разпознае JSON. Всяка проверка записва реалния код, време за отговор, размер и евентуална грешка. Множество последователни грешки (конфигурируемо, по подразбиране 2) предизвикват инцидент.

JSON path асерции

Самите статус кодове често не са достатъчни за API. Health endpoint може да върне 200 с body {"status": "degraded", "db": "down"} – все още 200, но определено искаш да го знаеш. API за цени може да върне 200 с body, където data.price е паднало до null. API за търсене може да върне 200 с results: [], защото индексът е паднал.

За такива случаи конфигурирай JSON path асерция. Задай пътя (напр. data.status или health.checks.db) и очакваната стойност (напр. healthy, true или конкретно число). При всяка проверка отговорът се декодира от JSON, а стойността по пътя се сравнява. Несъответствието води до неуспех на проверката, независимо от HTTP статуса.

Синтаксисът на пътя е точкова нотация с индекси: data.items[0].id работи, също така users.john.email. Асертираната стойност се сравнява като string, така че "true" съвпада с bool true, а числата съвпадат и като string, и като число.

Шаблони за удостоверяване

Двата най-често срещани начина за удостоверяване работят веднага. За Bearer token-и (OAuth, JWT, API ключове) използвай поле headers: {"Authorization": "Bearer eyJhbGciOi..."}. Токенът стои в конфигурацията на монитора и се изпраща при всяка проверка. За basic auth използвай специалните полета потребител/парола – съхраняват се и се комбинират в стандартен header.

Ако auth изисква подписване за всяка заявка или refresh на токена, е по-сложно. Два разумни шаблона: (1) конфигурирай дългоживеещ токен на service акаунт специално за мониторинг, или (2) направи незащитен health endpoint, който отразява статуса на истинския защитен, и го монитори. Повечето модерни API-та вече го имат вградено.

Шаблони, които препоръчваме

• Един монитор на критичен endpoint. Не тествай всеки – избери 5-10, чийто отказ би значил реална вреда.
• Използвай точни кодове. По подразбиране 200-399 е твърде широко за API. Endpoint за създаване трябва да връща точно 201; идемпотентен – точно 200; endpoint за логин – точно 200 (успех) или 401 (добре оформена грешка – не 500).
• Комбинирай статус с JSON асерция. Заедно хващат регресии както в транспортния слой, така и в съдържанието. Сам статус не улавя content грешки; самата JSON асерция е чуплива при пренасочвания.
• Задай праг за време на отговор. Деградацията на API е ранен индикатор за проблеми с зависимости. Монитор с rt_threshold_ms = 800 показва, че API забавя, преди да спре напълно.
• Дръж body малък. Проверката е всяка минута – големи body-та хабят трафик и от двете страни. Представителни, но минимални payload-и са достатъчни.

Комбинирай с други видове монитори

За всеки API endpoint, мониторът за API проверява, че извикването работи. Отделен ping или порт монитор следи дали хостът е жив. Проверка на SSL/домейн за същото име на хоста хваща проблеми с сертификата и регистрацията. Sub-monitor на DNS следи за промени в записите, които могат да подсказват подмяна. Заедно четири монитора на API дават пълна картина при минимално припокриване.

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

Отвори инструмента, натисни "Добави монитор", избери тип "API". Постави URL. Отвори секцията Разширени. Избери метода, постави заглавки като JSON, добави body ако е нужно, задавай basic auth ако го използваш, въведи очаквани кодове (напр. 200 или 200,201). Добави JSON path асерция, ако е приложимо. Настрой интервал и праг за потвърждение. Запази. От следващия цикъл мониторът прави заявка към твоето API точно както би направил интегратор, валидира отговора и алармира веднага при регресия.

Често задавани въпроси

• Какви HTTP методи мога да използвам за мониторинг на API?

  GET, POST, PUT, DELETE, PATCH и HEAD. Конфигурирай метода за всеки монитор – за write endpoint-и (POST/PUT/PATCH) тялото на заявката също се настройва като string JSON или form data.

• Как работят JSON асерциите?

  Подавате JSON път (напр. data.status или results[0].id) и очаквана стойност. Мониторът получава отговора, парсира го като JSON, извлича стойността по пътя и сравнява с очакваното. Ако не съвпада, проверката се проваля с грешка "assertion failed", показвайки реалната стойност.

• Мога ли да изпращам auth заглавки?

  Да. Можеш да конфигурираш свои HTTP заглавки за всеки монитор – Authorization токени, API ключове, content-type, каквото трябва. Стойностите на заглавките се съхраняват криптирано в базата. За Basic Auth има отделно поле за username/password, което автоматично подписва заявката.

• Какво ако моето API връща 200 с грешка в payload?

  Често срещан случай: API връща HTTP 200, но body-то казва {"status":"error"}. Наивният uptime монитор мисли, че всичко е наред. Използвай JSON асерция status == "ok", за да го хванеш – асерцията се проваля и мониторът отчита DOWN, дори HTTP статусът да е 200.

• Как да се справя с API с rate limit?

  Настрой интервала на проверките така, че да съответства на лимита на API (напр. 5-минутен интервал, ако API позволява 12 повиквания/час). Всяка проверка се брои като едно повикване от един регион. Мултирегионалните проверки умножават броя на повикванията – използвай single-region ако твоето API има строги лимити.