Dobre API wygląda nudno w najlepszym znaczeniu: przewidywalne adresy URL, uczciwe błędy, małe i stabilne schematy, żadnych niespodzianek. To zasady, które kształtują Noxyr Server API, zapożyczone ze standardów branżowych stojących za Stripe, Resend, OpenAI i oficjalnym API Discorda.
1. Wersjonowane adresy URL
Każdy endpoint znajduje się pod /api/v1/. Gdy dodajemy zmiany łamiące kompatybilność, trafiają pod /api/v2/: stare integracje dalej działają. Discord robi to samo z /api/v10/. Jeśli twoje API nie jest wersjonowane, każda zmiana schematu to zgłoszenie do obsługi klienta.
2. Najpierw zasoby, potem akcje
Endpointy Noxyr nazywają się rzeczownikami: server, tickets, activity, invoices, reviews, giveaways. Wszystkie są tylko do odczytu, wszystkie to GET. Gdy dodamy zapisy, będą to POST/PATCH/DELETE na tych samych zasobach. To czysto pasuje do konwencji REST i utrzymuje model mentalny w małym rozmiarze.
3. Tokeny Bearer, jeden sekret
Uwierzytelnianie wygląda tak: Authorization: Bearer nxr_.... Żadnych podpisywanych żądań, żadnego przepływu OAuth dla danych serwera tylko do odczytu. Nowoczesne API dla deweloperów zbiegają się do tego, bo działa wszędzie: w curl, przeglądarkach, Postmanie, na brzegach serverless. Discord też używa tokenów bearer dla użytkowników autoryzowanych przez OAuth; ten wzorzec jest uniwersalny.
4. Przechowuj tylko hashe
Każdy klucz Noxyr jest po stronie serwera haszowany algorytmem SHA-256. Surowa wartość jest pokazywana raz, przy generowaniu, i nigdy więcej. Gdyby nasza baza wyciekła, żaden klucz nie nadawałby się do użycia. Stripe, GitHub, Resend i każdy inny dobrze prowadzony dostawca API robi tak; odwracalne przechowywanie kluczy to czerwona flaga.
5. Precyzyjne zakresy
Jeden klucz, sześć niezależnych przełączników. Recenzje to dane publiczne; sprzedaż jest prywatna. Ich rozdzielenie oznacza, że możesz udostępnić partnerowi marketingowemu klucz tylko do recenzji, a liczby przychodów trzymać za innym przełącznikiem. Zmiany zakresu działają od razu (sprawdzane przy każdym żądaniu), więc unieważnienie nie wymaga rotacji klucza.
6. Uczciwe odpowiedzi o błędach
Każdy błąd to JSON ze stabilnym kodem czytelnym dla maszyn i komunikatem dla człowieka:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }Kody czytelne dla maszyn ułatwiają ponawianie i panele. Komunikaty dla ludzi przyspieszają debugowanie. Wyszukiwania „discord increased api errors” w lipcu 2026 roku (Google Trends: „breakout”) pokazują, co się dzieje, gdy błędy są nieczytelne: użytkownicy zgadują.
7. Szeregi czasowe wypełnione zerami
Endpoint /api/v1/activity zwraca każdy dzień z żądanego zakresu, nawet gdy liczba wynosi zero. Frontend nie musi wypełniać luk; wykresy nie skaczą między rzadkimi datami. To drobiazg z dużym zyskiem na wygodzie.
8. Limity zapytań w nagłówkach
Każda odpowiedź zawiera nagłówki RateLimit-*, dzięki czemu klienci mogą zwolnić, zanim trafią w 429. To standardowy format z szkicu IETF, ten sam kształt co w GitHub i innych nowoczesnych API, więc każda istniejąca biblioteka klienta, która go obsługuje, działa od razu.
9. Liberalne CORS dla danych tylko do odczytu
Endpointy tylko do odczytu wysyłają Access-Control-Allow-Origin: *. Ponieważ uwierzytelnia klucz, a nie źródło, otwarcie CORS nie kosztuje nic pod względem bezpieczeństwa i pozwala narzędziom przeglądarkowym wywoływać API bezpośrednio, bez proxy i bez obejść dla localhost.
10. Małe, stabilne schematy
Każda odpowiedź mieści się na jednym ekranie. Brak opcjonalnych zagnieżdżonych obiektów, brak pól, które pojawiają się tylko przy włączonej fladze funkcji. Małe schematy można cache'ować, testować i łatwo opisać w TypeScript.
Zobacz to w praktyce: tutorial Server API. A gdy sam Discord się psuje, zobacz co naprawdę oznaczają te błędy API Discorda.