Lekce 15 - Dokumentace k Node.js API
V minulé lekci, Zabezpečení endpointů v Node.js na roli administrátora, jsme naprogramovali zabezpečení endpointů API na roli administrátora pomocí route handler.
Tato lekce poskytuje dokumentaci pro API databáze filmů včetně ukázkových požadavků a odpovědí. Bude vám užitečná hned několikrát:
- Představení API - Pokud jste sem přišli ještě před programováním API, získáte přehled o tom, jak bude projekt fungovat a jeho tvorba pro vás bude pak snazší.
- Shrnutí API - Po dokončení projektu tato lekce shrnuje jeho funkčnost a pomáhá zapamatování principů RESTful API.
- Tvorba klienta - Pokud programujete klienta k tomuto API, např. v kurzech Základy React nebo Základy Angular frameworku, můžete si jednoduše ověřit, zda posíláte správně strukturovaný požadavek nebo jaký bude od API formát odpovědi.
- Tvorba serveru - Pokud programujete server v jiné technologii, ale měl by fungovat s klientem původně tvořeným pro toto API (viz bod výše), můžete si jednoduše zkontrolovat, že vaše endpointy vracejí přesně to, co mají. Jako toho API pracují např. servery v kurzech Spring Boot - Filmová databáze nebo ASP.NET Core Web API.
Vidíme, že dokumentace je zkrátka dobrá praktika, proto i vy pro svá API vytvářejte podobnou dokumentaci, jako je tato. Můžete k tomu využít automatizovaných nástrojů jako např. https://swagger.io/ nebo ji napsat ručně. Pojďme si API popsat.
API databáze filmů
API spravuje filmy, režiséry a herce. Routování je RESTful (posíláme tedy požadavky typu GET, POST, PUT a DELETE). Komunikace probíhá ve formátu JSON. V případě chyby API vrátí chybový kód 4XX.
Čtení dat z API je vždy povoleno.
Editace dat v API je povolena v projektu z lekce Dokončení API v Node.js - Metody GET a PUT. V projektu z poslední lekce, Zabezpečení endpointů v Node.js na roli administrátora, je editace dat podmíněna přihlášením uživatele s rolí administrátora. Autentizace a autorizace API je popsána na konci tohoto dokumentu.
Lidé
API nám umožňuje spravovat režiséry a herce. Souhrnně o nich hovoří
jako o lidech a liší se od sebe pouze atributem role.
Vytvoření režiséra
Pošleme požadavek POST na adresu /api/people,
který obsahuje JSON s daty nové osoby. API vrátí jako odpověď nově
vytvořený objekt spolu s ID, které mu přiřadilo.
Požadavek
{ "name": "James Cameron", "birthDate": "1954-08-16", "country": "Kanada", "role": "director", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ..." }
Odpověď
{ "name": "James Cameron", "birthDate": "1954-08-16T00:00:00.000Z", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director", "_id": "64047109b80ed070c5425fb8", "__v": 0 }
Do odpovědí serveru vkládá Mongoose navíc verzovací
parametr __v. Ten ničemu nevadí, ale nemusí v odpovědi
být.
Vytvoření herce
Pošleme požadavek POST na adresu
/api/people.
Požadavek
{ "name": "Dwayne Johnson", "birthDate": "1972-05-02", "country": "USA", "role": "actor", "biography": "Nejprve atlet a hráč amerického fotbalu, poté wrestler a následně herec." }
Odpověď
{ "name": "Dwayne Johnson", "birthDate": "1972-05-02T00:00:00.000Z", "country": "USA", "biography": "Nejprve atlet a hráč amerického fotbalu, poté wrestler a následně herec.", "role": "actor", "_id": "64047e10b3201657ed2b5977", "__v": 0 }
Výpis režisérů
Pošleme požadavek GET na adresu
/api/directors. Můžeme uvést také parametr limit pro získání
jen omezeného počtu výsledků, např. jako
/api/directors?limit=10.
Odpověď
[ { "_id": "64047109b80ed070c5425fb8", "name": "James Cameron", "birthDate": "1954-08-16T00:00:00.000Z", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director", "__v": 0 } ]
Výpis herců
Pošleme požadavek GET na adresu /api/actors.
Můžeme uvést také parametr limit pro získání jen omezeného počtu
výsledků, např. jako /api/actors?limit=10.
Odpověď
[ { "_id": "64047e10b3201657ed2b5977", "name": "Dwayne Johnson", "birthDate": "1972-05-02T00:00:00.000Z", "country": "USA", "biography": "Nejprve atlet a hráč amerického fotbalu, poté wrestler a následně herec.", "role": "actor", "__v": 0 } ]
Detail člověka
Pošleme požadavek GET na adresu s ID člověka, např.
/api/people/64047109b80ed070c5425fb8.
Odpověď
{ "_id": "64047109b80ed070c5425fb8", "name": "James Cameron", "birthDate": "1954-08-16T00:00:00.000Z", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director", "__v": 0 }
Úprava člověka
Pošleme požadavek PUT na adresu s ID člověka, např.
/api/people/64047109b80ed070c5425fb8.
Požadavek
{ "name": "James Francis Cameron", "birthDate": "1954-08-16", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director" }
Odpověď
{ "_id": "64047109b80ed070c5425fb8", "name": "James Francis Cameron", "birthDate": "1954-08-16T00:00:00.000Z", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director", "__v": 0 }
Smazání člověka
Pošleme požadavek DELETE na adresu s ID člověka, např.
/api/people/64047109b80ed070c5425fb8. Navrácen je odstraněný
objekt.
Odpověď
{ "_id": "64047109b80ed070c5425fb8", "name": "James Francis Cameron", "birthDate": "1954-08-16T00:00:00.000Z", "country": "Kanada", "biography": "Byl chudý řidič kamionu, když začínal. Je pětkrát ženatý ...", "role": "director", "__v": 0 }
Filmy
Vytvoření filmu
Pošleme požadavek POST na adresu
/api/movies.
Požadavek
{ "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": ["63d27a785060fe3ab7c1df1a"], "isAvailable": true, "genres": ["sci-fi"] }
Odpověď
{ "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "64047e10b3201657ed2b5977" ], "genres": [ "sci-fi" ], "isAvailable": true, "_id": "640471c9b80ed070c5425fbc", "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0 }
Výpis filmů
Pošleme požadavek GET na adresu /api/movies.
Do query parametrů můžeme vložit filtrovací pravidla, finální adresa by
tedy mohla vypadat například
/api/movies?genre=sci-fi&limit=3. Zpět dostaneme seznam všech
filmů, pro každý film nedostáváme informace o konkrétních hercích a
režisérovi, pouze jejich ID.
Filtrovací parametry
| Pravidlo | Popis |
|---|---|
| directorID | vybere filmy podle id režiséra |
| actorID | vybere filmy s daným hercem |
| genre | získá filmy, které mají alespoň tento žánr |
| fromYear | vybere filmy vydané po zadaném roce |
| toYear | vybere filmy vydané před zadaným rokem |
| limit | získá pouze omezený počet filmů |
Odpověď
[ { "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "64047e10b3201657ed2b5977" ], "genres": [ "sci-fi" ], "isAvailable": true, "_id": "640471c9b80ed070c5425fbc", "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0 } ]
Detail filmu
Pošleme požadavek GET na adresu s ID filmu, např.
/api/movies/640471c9b80ed070c5425fbc. Součástí odpovědi API
jsou u filmu jak ID režiséra a herců (directorID a
actorIDs), tak odpovídající objekty (director a
kolekce objektů actors) s ID a jménem.
Odpověď
{ "_id": "640471c9b80ed070c5425fbc", "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "64047e10b3201657ed2b5977" ], "genres": [ "sci-fi" ], "isAvailable": true, "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0, "director": { "_id": "64047109b80ed070c5425fb8", "name": "James Francis Cameron" }, "actors": [ { "_id": "64047e10b3201657ed2b5977", "name": "Dwayne Johnson" } ] }
Úprava filmu
Pošleme požadavek PUT na adresu s ID filmu, např.
/api/movies/640471c9b80ed070c5425fbc.
Požadavek
{ "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": ["63d27a785060fe3ab7c1df1a"], "isAvailable": false, "genres": ["sci-fi"] }
Odpověď
{ "_id": "640471c9b80ed070c5425fbc", "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "63d27a785060fe3ab7c1df1a" ], "genres": [ "sci-fi" ], "isAvailable": false, "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0 }
Smazání filmu
Pošleme požadavek DELETE na adresu s ID filmu,
/api/movies/640471c9b80ed070c5425fbc. Odpovědí je odstraněný
film.
Odpověď
{ "_id": "640471c9b80ed070c5425fbc", "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "63d27a785060fe3ab7c1df1a" ], "genres": [ "sci-fi" ], "isAvailable": false, "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0 }
Žánry
Validní hodnoty žánrů filmů nabízí API ke stažení jako jednoduchý seznam.
Výpis žánrů
Pošleme požadavek GET na adresu
/api/genres.
Odpověď
[ "sci-fi", "adventure", "action", "romantic", "animated", "comedy" ]
Registrace a login
Pokud používáte projekt z poslední lekce Zabezpečení endpointů v Node.js na roli administrátora, endpointy pro editaci dat fungují pouze pro přihlášené uživatele, kteří mají roli administrátor. Tuto verzi API lze nasadit na internet, aniž bychom se museli bát, že nám data nějaký vtipálek vymaže. Pro lokální testování ovšem používáme verzi bez autentizace z lekce Dokončení API v Node.js - Metody GET a PUT.
API neumožňuje nastavit uživatele jako administrátora, toto nastavení je nutné pro konkrétního uživatele provést ručně v databázi.
Uživatelé
Registrace
Pro registraci nového uživatele pošleme POST požadavek
na /api/user:
Požadavek
{ "email": "[email protected]", "password": "hesloJeVeslo123" }
Odpověď
{ "email": "[email protected]", "isAdmin": false, "_id": "642b1a78676469114695ea0e", "__v": 0 }
Přihlášení
Pošleme POST požadavek na /api/auth:
Požadavek
{ "email": "[email protected]", "password": "hesloJeVeslo123" }
Odpověď
{ "_id": "642b1a78676469114695ea0e", "email": "[email protected]", "isAdmin": false }
Odhlášení
Pošleme DELETE požadavek na /api/auth
Odpověď
Uživatel odhlášen
Informace o současném uživateli
Pošleme GET požadavek na /api/auth
Odpověď
{ "_id": "642b1a78676469114695ea0e", "email": "[email protected]", "isAdmin": false }
Pokud jste na tuto lekci přišli ještě před tvorbou API, můžete se vrátit na lekci Kompletní RESTful API v Node.js.
V následujícím kvízu, Kvíz - Serverový JavaScript Node.js, si vyzkoušíme nabyté zkušenosti z kurzu.
