Введение в REST API на TypeScript

Что такое API

API (Application Programming Interface) — это контракт, который позволяет одной программе общаться с другой. Веб-API говорит по HTTP: клиент отправляет запрос, сервер возвращает ответ — обычно с данными в формате JSON.

REST (Representational State Transfer) — самый распространённый стиль проектирования таких API. Это не протокол и не библиотека — это набор правил о том, как строить URL, методы и ответы. HTTP передаёт данные; REST говорит, как их организовать.

Центральная идея — ресурс: у каждой вещи, которой управляет ваш API — пользователя, заказа, фотографии — есть свой URL, например /users/7.

Правила REST

REST опирается на несколько принципов:

Клиент — сервер — обе стороны разделены и развиваются независимо.
Отсутствие состояния — каждый запрос несёт всё, что нужно серверу; между запросами сервер ничего не запоминает.
Единообразный интерфейс — одни и те же URL, методы и коды состояния везде означают одно и то же.
Кэшируемость — ответы могут сообщить «этот ответ можно использовать повторно», экономя обращения к серверу.
Слоистость — прокси, шлюзы и балансировщики нагрузки могут находиться между клиентом и сервером, и ни одна из сторон этого не заметит.

Один запрос, один ответ

Любое взаимодействие с API — это такой цикл: уходит запрос (метод + URL + необязательное тело), приходит ответ (код состояния + заголовки + тело). Вот один полный цикл на TypeScript — демонстрация запускает крошечный локальный сервер, чтобы программа могла отработать и завершиться сама.

Полный цикл обмена

Клиент запрашивает GET /users/1; сервер отвечает статусом 200 OK, типом содержимого и телом в формате JSON. Каждая страница этой группы строится на этом цикле.

Напишите программу на TypeScript, которая показывает один полный цикл REST-обмена: запустите крошечный локальный сервер node:http на порту 0, обработчик которого отвечает JSON-объектом пользователя и заголовком Content-Type, отправьте GET-запрос на /users/1 с помощью fetch, выведите строку запроса, статус ответа, тип содержимого и тело, затем закройте сервер.

> Вывод: программа на TypeScript и захваченный вывод

Prompt

Напишите программу на TypeScript, которая показывает один полный цикл REST-обмена: запустите крошечный локальный сервер node:http на порту 0, обработчик которого отвечает JSON-объектом пользователя и заголовком Content-Type, отправьте GET-запрос на /users/1 с помощью fetch, выведите строку запроса, статус ответа, тип содержимого и тело, затем закройте сервер.

Вывод: программа на TypeScript и захваченный вывод

import { createServer } from "node:http"

async function main(): Promise<void> {
  // Крошечный локальный сервер для демонстрации. Порт 0 означает «любой свободный порт»,
  // поэтому пример никогда не конфликтует с тем, что уже запущено.
  const server = createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "application/json" })
    res.end('{"id": 1, "name": "Ana"}')
  })
  await new Promise<void>(resolve => server.listen(0, () => resolve()))
  const port = (server.address() as { port: number }).port

  const res = await fetch(`http://localhost:${port}/users/1`)
  const body = await res.text()

  console.log("запрос: GET /users/1")
  console.log("статус: ", res.status, res.statusText)
  console.log("тип:    ", res.headers.get("content-type"))
  console.log("тело:   ", body)

  server.close()
}

main()

Методы, коды состояния и ограничения

Методы HTTP соответствуют четырём операциям над данными (CRUD):

GET прочитать ресурс · POST создать · PUT заменить · PATCH изменить часть · DELETE удалить.

Коды состояния сообщают, как всё прошло: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.

И у REST есть честные ограничения: он не создан для потоков в реальном времени, ответ может нести больше или меньше данных, чем хотел клиент, а версионирование публичного API требует дисциплины. Знать ограничения — часть знания стиля.