Към съдържанието
Sursa Developers

Адрес на API и среди

Sursa API има собствен адрес, отделен от адреса, на който хората отварят Sursa в браузъра. Всички пътища започват с /v1.

Къде работи SursaАдрес на APIТози портал
Облакът на Sursahttps://api.sursa.comhttps://developers.sursa.com
Собствената ви инсталацияhttps://api.<your domain>, както го е настроил администраторът ви/developers/ на адреса на API
Инсталацията ви без отделен адрес на APIосновният адрес на инсталацията/developers/ на основния адрес

Адресът на API обслужва само API: на него няма страница за вход, бисквитки и уеб интерфейс. Всяка заявка се удостоверява с API ключ или с OAuth токен за достъп. Адресът може да се обслужва от няколко сървъра зад балансьор на натоварването; не е нужно интеграцията ви да знае колко са те.

Интеграциите, които извикват API на основния адрес (например https://app.sursa.com/v1), продължават да работят. Вж. Преминаване към адреса на API за малкото разлики и за преминаването стъпка по стъпка.

Базов URL адрес

Изграждайте всяка заявка от един базов URL адрес в конфигурацията си, така че един и същ код да работи с всяка среда:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Използвайте само HTTPS и не допускайте ключът да попада в дневниците на изпращаните от вас заявки.

Версия и спецификация

GET /v1/health показва дали адресът работи, и връща версията на Sursa, която го обслужва. Отговаря без ключ, затова може да я използвате в мониторинга:

curl https://api.sursa.com/v1/health
{"ok": true, "version": "v1.4.0"}

Това е версията на изданието на Sursa, а не на API. Версията на API е info.version на спецификацията му. Спецификацията на API във формат OpenAPI 3.1 е публикувана на същия адрес, без удостоверяване:

ПътСъдържание
GET /openapi.jsonПубличната спецификация, с този адрес в servers.
GET /v1/openapi-public.jsonСъщата спецификация. Поддържа ETag и If-None-Match.

Използвайте я, за да генерирате клиент, да импортирате API в инструмент като Postman или да проверявате в CI, че интеграцията ви използва само операции от очакваната версия. Справочникът на API на този портал е създаден от същия файл.

Тестване

В Sursa няма отделен тестов режим: всяка заявка с ключ работи с реалните данни на своята организация. За да разработвате и тествате безопасно:

  • Създайте отделен ключ за разработка с най-тясната роля и с най-тесните обхвати, които работата изисква.
  • Записвайте в отделна колекция, например sandbox, която вижда само вашият екип, и я изтрийте, когато приключите.
  • Ако компанията ви има отделна организация или инсталация на Sursa за тестване, насочете базовия URL адрес и ключа към нея. Нищо друго в кода ви не се променя.
  • Направете повторните опити безопасни от самото начало: изпращайте Idempotency-Key с всяка заявка POST и PATCH.

Конзолата Изпробвайте на страницата на всяка операция в справочника на API изпраща реални заявки с ключ, който поставяте в нея. Ключът остава в паметта на раздела на браузъра и се изпраща само до адреса на API.

Мрежови изисквания

  • Изходящ HTTPS (порт 443) от вашите сървъри към адреса на API.
  • В правилата на защитната стена разрешавайте името на хоста, а не фиксирани IP адреси, където мрежата ви го позволява: сървърите зад адреса може да се сменят при увеличаване на капацитета.
  • Приложенията в браузъра може да извикват API директно: отговорите разрешават всеки origin (Access-Control-Allow-Origin: *) без бисквитки. Имайте предвид, че ключ, използван в браузър, се вижда от потребителя на този браузър.