Vlastní API

Až doteď jsi byl na straně, která se ptá. Teď se podíváme na druhou stranu: tvoje aplikace odpovídá.

Kdy vlastní API potřebuješ

1. Prohlížeč mluví se serverem

   Skoro vždycky. Když formulář něco uloží, mluví s tvým API, i když si tak neříká.

2. Cizí služba ti něco posílá

   Platební brána oznámí zaplacení, e-mailová služba doručení. Říká se tomu webhook.

3. Někdo se napojuje na tebe

   Mobilní aplikace, partner, tvůj vlastní skript.

Anatomie koncového bodu

Koncový bod je jedna adresa, která něco umí.

Tři kontroly, které musí být na serveru

Tohle je nejdůležitější část celé lekce.

1. Je uživatel přihlášený?

   Autentizace. Kdo se ptá?

2. Smí to udělat?

   Autorizace. Uživatel může být přihlášený a přesto nesmět mazat cizí rezervace.

3. Dávají data smysl?

   Validace. Datum v minulosti, záporný počet, prázdné jméno, e-mail bez zavináče.

Vytvoř koncový bod [METODA] /api/[CESTA], který [CO DĚLÁ].

Povinné:
1. Ověř, že je uživatel přihlášený. Když ne, vrať 401.
2. Ověř, že smí právě tuhle věc. Když ne, vrať 403.
3. Zkontroluj vstupní data – typy, povinnost, rozsahy.
 Při chybě vrať 400 a seznam problémů.
4. Chybové odpovědi ve srozumitelném tvaru, česky, bez technických detailů.
5. Nikdy nevracej víc dat, než je potřeba – žádná hesla, žádné cizí údaje.

Než to napíšeš, popiš mi:
- Jaký tvar má vstup a jaký výstup.
- Které kontroly kde probíhají.
- Co se vrátí v každé chybové situaci.

Chybové kódy

Používej ty správné. Ušetří to hodně zmatku při hledání chyb.

Webhooky

Když ti cizí služba něco oznamuje, platí navíc dvě věci:

1. Ověř, že to opravdu poslali oni

   Služby posílají podpis, kterým se dá zpráva ověřit. Bez toho ti může kdokoliv napsat „zaplaceno“.

2. Počítej s tím, že přijde vícekrát

   Stejné oznámení může dorazit dvakrát. Aplikace se musí zachovat stejně jako při jednom – jedna platba, jeden e-mail.