API-эндпоинты

Эндпоинт — адрес, который возвращает не HTML-страницу, а данные: JSON, текст, файл. В Astro это файл .js или .ts в src/pages/, который экспортирует функции с именами HTTP-методов: GET, POST и другие. Каждая функция возвращает стандартный объект Response.

Статический эндпоинт

Сделаем список статей в формате JSON. Создайте src/pages/api/posts.json.ts:

// src/pages/api/posts.json.ts
import type { APIRoute } from 'astro';
import { getCollection } from 'astro:content';
 
export const GET: APIRoute = async () => {
  const posts = await getCollection('blog');
  const list = posts.map((post) => ({
    id: post.id,
    title: post.data.title,
  }));
 
  return new Response(JSON.stringify(list), {
    headers: { 'Content-Type': 'application/json' },
  });
};

Откройте http://localhost:4321/api/posts.json — браузер покажет массив статей. Расширение .json в имени файла становится частью адреса. В статическом режиме Astro выполнит функцию при сборке и сохранит результат файлом dist/api/posts.json.

Эндпоинт по запросу

Чтобы принимать данные от посетителей, эндпоинт должен работать на сервере — нужен адаптер из прошлого урока. Создайте src/pages/api/likes.ts:

// src/pages/api/likes.ts
import type { APIRoute } from 'astro';
 
export const prerender = false;
 
let likes = 0;
 
export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  likes += body.count ?? 1;
 
  return Response.json({ likes });
};

Функция читает тело запроса, увеличивает счётчик и отвечает JSON. Response.json() — короткая запись для ответа с заголовком Content-Type: application/json. Счётчик хранится в памяти сервера и сбросится при перезапуске; в настоящем проекте его держат в базе данных.

Вызов из браузера

Эндпоинт вызывают обычным fetch(), например из React-острова LikeButton.jsx:

// src/components/LikeButton.jsx
async function sendLike() {
  const response = await fetch('/api/likes', {
    method: 'POST',
    body: JSON.stringify({ count: 1 }),
  });
  const data = await response.json();
  console.log(data.likes);
}

После каждого вызова в консоли браузера появится новое общее число лайков.

Что получает функция

Частая ошибка

Создают эндпоинт с POST на статическом сайте без prerender = false. При сборке Astro вызывает только GET, поэтому POST на выложенном сайте не работает. Эндпоинты, которые принимают данные, всегда помечайте export const prerender = false и подключайте адаптер.