Jak napsat svoji první REST HTTP API

Požadavek a odpověď

Požadavek i odpověď dodržují jistý formát, kterým se služby řídí. Zde je příklad požadavku pro vytvoření uživatele:

POST /api/users HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0
Accept: application/json
Content-Type: application/json
Content-Length: 71

{
  "name": "Jan Novák",
  "email": "jan.novak@example.com",
  "active": true
}

Můžeš zde vidět spoustu informací. Když si to rozdělíš, zjistíš, že to zas tak komplexní není:

Metoda – určuje typ operace, kterou má požadavek vykonat. Mezi základní patří:
- GET – pro získání dat, požadavek neobsahuje obsah.
- POST – pro tvorbu nových dat.
- PUT – pro úpravu dat – data z požadavku přepíší existující obsah.
- PATCH – částečná úprava dat – lze vynechat pole, která mají zůstat stejná.
Verze HTTP – pro nás většinou irelevantní, HTTP server a klient si ji spravují sami.
Hlavičky – většinou obsahují „metadata“ a neslouží k přenosu samotných dat. V příkladu můžeme vidět Content-Type, které slouží pro označení formátu obsahu (zde JSON), a například User-Agent, který HTTP klient nastavuje pro označení klienta. Mozilla/5.0 v tomto případě znamená, že se pravděpodobně jednalo o prohlížeč.
Obsah – v případě, že se jedná o požadavek pro modifikaci nebo nahrání dat, je ve většině případů přítomen i obsah. Ten je ve formátu, který specifikuje již zmíněná Content-Type hlavička.

Nyní přichází druhá část našeho HTTP požadavku: odpověď:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/1024
Content-Length: 118

{
  "id": 1024,
  "name": "Jan Novák",
  "email": "jan.novak@example.com",
  "active": true,
  "createdAt": "2026-09-06T14:32:00Z"
}

Odpověď je vcelku podobná požadavku, vyznačil jsem tedy primárně pro nás důležitý status a popis status kódu:

Status – označuje výsledek požadavku. Je zpravidla označen číslem. Není důležité pamatovat si, co které statusy znamenají (i když po nějaké té době se některé stejně člověku vryjí do paměti – 200, 201, 400, 404…), důležité je zapamatovat si alespoň meze, které určují výsledek:
- 200–299 – úspěch
- 400+ – chyba apod.
Krátký popis statusu – je spjat se statusem, v podstatě krátké slovní vyjádření číselného kódu (takže 201 – Created).

Když jsme si vysvětlili, jak požadavek probíhá, pojďme si to zkusit naprogramovat.

Příklad v TypeScriptu

V tomto příkladu využijeme knihovnu Elysia pro vytvoření jednoduchého API pro vytvoření uživatele:

import { Elysia, t } from 'elysia'

const app = new Elysia()
  /* Vytvoříme nový endpoint (místo pro zpracování požadavku) pro metodu POST.
     Při tvoření endpointu můžeme mít více metod na jedné cestě. */
  .post(
    '/api/users', // Cesta, na které bude naše API, obvykle prefix /api
    ({ body, set }) => { // Zpracování požadavku
      const name = body.name; /* .name .email .active */
      set.status = 201; // Nastaví výsledný status
      set.headers['Location'] = `/api/users/${newUser.id}`; // Nastaví hlavičku "Location:"
    },
    { // Validace těla požadavku
      body: t.Object({
        name: t.String({ minLength: 1 }),
        email: t.String({ format: 'email' }),
        active: t.Boolean()
      })
    }
  )

Abychom následně z klienta zavolali naši API, můžeme využít knihovnu Eden pro Elysii:

// Předtím: npm add @elysiajs/eden
export const api = treaty<typeof app>('localhost:3000' /* Adresa naší API */);

const { data, error } = await api.api.users.post({
  // Simuluje požadavek s metodou POST na cestu /api/users
  // s tělem, které je samo natypováno podle instance app:
  name: 'Jan Novák',
  email: 'jan.novak@example.com',
  active: true
})

if (error) { // Operace neskončila 200–299
  // error.value obsahuje typovanou chybu (např. validační)
  console.error(error.value)
  return
}

Reference

Přehled status kódů: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
Přehled HTTP ve webu: https://developer.mozilla.org/en-US/docs/Web/HTTP
Elysia – přehled: https://elysiajs.com/at-glance.html
Zabezpečení API pomocí bearer tokenu: https://blog.postman.com/what-is-a-bearer-token/
Elysia.js – Bearer token: https://elysiajs.com/plugins/bearer