Přeskočit na obsah

Principy API a autentizace

docsVerze 0.1.0CS

Veřejný popis a přístup k API

Sekce “Veřejný popis a přístup k API”

Veřejná API reference může popisovat službu, která vyžaduje autentizaci. Viditelnost dokumentace neuděluje oprávnění k volání API. Každá služba určuje vlastní klientské klíče, scopes, limity a životní cyklus. Získání přístupu popisuje její konkrétní návod.

OpenAPI popisuje operace, vstupy, odpovědi a bezpečnostní schémata. Strojově čitelný kontrakt má vlastní verzi. Změna nástroje, který kontrakt zobrazuje, nemění samotné API. Návrhový kontrakt není důkazem nasazené implementace.

Příklad používá nefunkční host a zástupný token; nic neposílá do produkce:

GET /example-items HTTP/1.1
Host: api.example.invalid
Authorization: Bearer EXAMPLE_TOKEN_DO_NOT_USE

Skutečný klíč patří do bezpečného serverového nastavení příslušného klienta, nikoli do veřejného webu či dokumentace.

401 zpravidla označuje chybějící či neplatnou autentizaci; 403 chybějící oprávnění. Služba může při překročení limitu vrátit 429. Řiďte se popsaným formátem chyby a retry pravidly konkrétního API. Citlivá data, tokeny a interní stacktrace nepřikládejte k veřejnému hlášení chyby.

© MiloslavHub · CC BY 4.0