Dobré API působí nudně v tom nejlepším slova smyslu: předvídatelné URL, poctivé chyby, malá stabilní schémata a žádná překvapení. Tyto principy utvářejí Noxyr Server API a vycházejí z průmyslových standardů, na kterých stojí Stripe, Resend, OpenAI a oficiální Discord API.
1. Verzované URL
Každý endpoint žije pod /api/v1/. Když přidáme změny, které nejsou zpětně kompatibilní, přistanou pod /api/v2/: staré integrace dál fungují. Discord dělá totéž s /api/v10/. Pokud vaše API neverzuje, každá změna schématu znamená zákaznický tiket.
2. Nejdřív zdroje, pak akce
Endpointy Noxyr jsou pojmenované podle podstatných jmen: server, tickets, activity, invoices, reviews, giveaways. Všechny jsou jen pro čtení a všechny přes GET. Až přidáme zápisy, půjdou jako POST/PATCH/DELETE na stejné zdroje. To se čistě mapuje na konvence REST a udržuje mentální model malý.
3. Bearer tokeny, jedno tajemství
Autentizace je Authorization: Bearer nxr_.... Žádné podepisované požadavky, žádný OAuth tok pro data serveru jen pro čtení. Moderní API pro vývojáře se k tomuto přiklánějí, protože funguje všude: curl, prohlížeče, Postman, serverless edge. Discord používá bearer tokeny i pro uživatele autorizované přes OAuth; tento vzor je univerzální.
4. Ukládat jen hashe
Každý klíč Noxyr je na serveru hashovaný pomocí SHA-256. Surová hodnota se zobrazí jednou při vygenerování a nikdy víckrát. Kdyby unikla naše databáze, žádný klíč by nebyl použitelný. Stripe, GitHub, Resend i každý další dobře vedený poskytovatel API to dělá: klíč, který jde zpětně přečíst, je varovný signál.
5. Jemně odstupňovaná oprávnění
Jeden klíč, šest nezávislých přepínačů. Recenze jsou veřejná data, tržby soukromá. Díky oddělení můžete sdílet klíč jen s recenzemi s marketingovým partnerem a čísla tržeb nechat za jiným přepínačem. Změny oprávnění platí okamžitě (kontroluje se při každém požadavku), takže odvolání nevyžaduje rotaci klíče.
6. Poctivé chybové odpovědi
Každá chyba je JSON se stabilním strojovým kódem a lidsky čitelnou zprávou:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }Strojově čitelné kódy usnadňují opakování a dashboardy. Lidsky čitelné zprávy zrychlují ladění. Hledání „discord increased api errors“ v červenci 2026 (Google Trends, „breakout“) ukazuje, co se stane, když jsou chyby nejasné: uživatelé hádají.
7. Časové řady bez děr
Endpoint /api/v1/activity vrací každý den v požadovaném rozsahu, i když je počet nula. Frontend nemusí vyplňovat mezery a grafy neskáčou mezi řídkými daty. Je to drobnost s velkým přínosem pro kvalitu práce.
8. Limity požadavků v hlavičkách
Každá odpověď nese hlavičky RateLimit-*, aby klienti mohli zpomalit dřív, než narazí na 429. Je to standardizovaný formát z návrhu IETF, stejný tvar jako u GitHubu a dalších moderních API, takže každá existující klientská knihovna, která ho mluví, funguje hned po instalaci.
9. Otevřené CORS pro data jen pro čtení
Endpointy jen pro čtení posílají Access-Control-Allow-Origin: *. Protože klíč je to, co autentizuje, a ne původ požadavku, otevřené CORS nic bezpečnostně nestojí a umožňuje nástrojům v prohlížeči volat API přímo, bez proxy a bez obcházení přes localhost.
10. Malá, stabilní schémata
Každá odpověď se vejde na jednu obrazovku. Žádné volitelné vnořené objekty, žádná pole, která se objeví jen při zapnutém feature flagu. Malá schémata se dají cachovat, testovat a snadno popsat v TypeScriptu.
V praxi: návod k Server API. A když má potíže samotný Discord, co ty chyby Discord API ve skutečnosti znamenají.