Пређите на садржај
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 и кључ на њу. Ништа друго у вашем коду се не мења.
  • Од почетка обезбедите безбедне поновне покушаје: уз сваки POST и PATCH пошаљите Idempotency-Key.

Конзола Испробајте на страници сваке операције у API референци шаље стварне захтеве са кључем који у њу налепите. Кључ остаје у меморији језичка прегледача и шаље се само на адресу API интерфејса.

Мрежни предуслови

  • Одлазни HTTPS (порт 443) са ваших сервера ка адреси API интерфејса.
  • У правилима заштитног зида дозволите име хоста, а не фиксне IP адресе, где год ваша мрежа то дозвољава: сервери иза адресе могу да се промене како се додаје капацитет.
  • Апликације у прегледачу могу директно да позивају API: одговори дозвољавају било који origin (Access-Control-Allow-Origin: *), без колачића. Имајте на уму да је кључ који се користи у прегледачу видљив кориснику тог прегледача.