NOVINKA - Online rekvalifikační kurz Java programátor. Oblíbená a studenty ověřená rekvalifikace - nyní i online.
NOVINKA – Víkendový online kurz Software tester, který tě posune dál. Zjisti, jak na to!

Lekce 15 - Dokumentace k Node.js API

Předchozí
Další

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.


 

Předchozí článek
Zabezpečení endpointů v Node.js na roli administrátora
Všechny články v sekci
Node.js - Serverový JavaScript
Přeskočit článek
(nedoporučujeme)
Kvíz - Serverový JavaScript Node.js
Článek pro vás napsal Martin Macura
Avatar
Uživatelské hodnocení:
119 hlasů
Aktivity