Pular para o conteúdo
Astro Astro

Endpoints

O Astro permite que você crie endpoints customizados para servir e processar todo tipo de dados. Isso pode ser usado para gerar imagens, expor um arquivo RSS ou os usar como rotas de API para construir uma API completa para o seu site.

Em sites gerados de forma estática, seus endpoints customizados são chamados durante a fase de build para produzir arquivos estáticos. Já em sites usando o modo SSR seus endpoints customizados se tornarão endpoints reais executados a cada requisição. Endpoints estáticos e SSR são definidos de maneira similar, mas os endpoints SSR suportam funcionalidades adicionais.

Endpoints de Arquivos Estáticos

Para criar um endpoint customizado, adicione um arquivo .js ou .ts no diretório /pages. A extensão do arquivo será removida durante o processo de build, portanto o nome do arquivo deve conter a extensão que você deseja que os dados usem, por exemplo src/pages/data.json.ts se tornará a rota /data.json.

Seus endpoints devem exportar uma função GET (opcionalmente assíncrona) que recebe um objeto de contexto com propriedades similares a global Astro. Aqui, ele retorna um objeto Response com um name e url, que o Astro irá chamar durante a build e utilizar seu conteúdo para gerar o arquivo.

src/pages/builtwith.json.ts
// Se tornará: /builtwith.json
export async function GET({params, request}) {
  return new Response(
    JSON.stringify({
      name: 'Astro',
      url: 'https://astro.build/'
    })
  )
}

Desde o Astro v3.0, 0 objeto Response retornado não tem mais que incluir a propriedade encoding. Por exemplo, para produzir uma imagem binária png:

src/pages/builtwith.json.ts
export async function GET({ params, request }) {
  const response = await fetch("https://docs.astro.build/assets/full-logo-light.png");
  return new Response(await response.arrayBuffer());
}

Também é possível adicionar validação de tipo à sua função com o tipo APIRoute:

import type { APIRoute } from 'astro';


export const GET: APIRoute = async ({ params, request }) => {...}

Roteamento dinâmico e a propriedade params

Os endpoints suportam as mesmas funcionalidades de roteamento dinâmico que as páginas. Nomeie seu arquivo com um nome de parâmetro entre colchetes e exporte uma função chamada getStaticPaths(). Assim será possível acessar o parâmetro utilizando a propriedade params passada para a função do endpoint.

src/pages/api/[id].json.ts
import type { APIRoute } from 'astro';


const usuarios = ["Sarah", "Chris", "Yan", "Elian"]


export const GET: APIRoute = ({ params, request }) => {
  const id = params.id;
  return new Response(
    JSON.stringify({
      name: usuarios[id]
    })
  )
}


export function getStaticPaths() {
  return [
    { params: { id: "0"} },
    { params: { id: "1"} },
    { params: { id: "2"} },
    { params: { id: "3"} }
  ]
}

Isso irá gerar quatro endpoints JSON durante a build: /api/0.json, /api/1.json, /api/2.json e /api/3.json. O roteamento dinâmico com endpoints funciona da mesma forma que nas páginas, porém, como um endpoint é uma função e não uma página, props não são suportadas.

request

Todos os endpoints recebem uma propriedade request, porém no modo estático você só tem acesso a propriedade request.url. Ela retorna o URL completo do endpoint atual e funciona da mesma forma que Astro.request.url funciona em páginas.

src/pages/request-path.json.ts
import type { APIRoute } from 'astro';


export const GET: APIRoute = ({ params, request }) => {
  return new Response(JSON.stringify({
      path: new URL(request.url).pathname
    })
  )
}

Endpoints do Servidor (Rotas de API)

Tudo descrito na seção de endpoints de arquivos estáticos também pode ser utilizado no modo SSR: arquivos podem exportar uma função GET que recebe um objeto de contexto com propriedades similares a global Astro.

Porém, diferente do modo static, quando você configura o modo server, os endpoints serão construídos no momento em que são requisitados. Isso desbloqueia novas funcionalidades que estão indisponíveis durante a build e permite que você construa rotas de API que respondem requisições e seguramente executam código no servidor em runtime.

Receita relacionada: Chame endpoints do servidor

Os endpoints do servidor tem acesso a propriedade params sem exportar a função getStaticPaths e podem retornar um objeto Response, permitindo que você defina códigos de status e cabeçalhos HTTP.

src/pages/[id].json.js
import { getProduct } from '../db';


export async function GET({ params }) {
  const id = params.id;
  const product = await getProduct(id);


  if (!product) {
    return new Response(null, {
      status: 404,
      statusText: 'Não encontrado'
    });
  }


  return new Response(
    JSON.stringify(product), {
      status: 200,
      headers: {
        "Content-Type": "application/json"
      }
    }
  );
}

Esse código responderá a qualquer requisição que corresponda à rota dinâmica. Por exemplo, se navegarmos para /capacete.json, params.id será capacete. Se capacete existir no banco de dados, o endpoint irá criar um objeto Response para responder com JSON e retornar um código de status HTTP de sucesso. Caso contrário, ele usará o objeto Response para responder com um erro 404.

No modo SSR, certos provedores requerem que o cabeçalho Content-Type retorne uma imagem. Neste caso, utilize um objeto Response para especificar uma propriedade headers. Por exemplo, para produzir uma imagem .png binária:

src/pages/astro-logo.png.ts
export async function GET({ params, request }) {
  const response = await fetch("https://docs.astro.build/assets/full-logo-light.png");
  const buffer = Buffer.from(await response.arrayBuffer());
  return new Response(buffer, {
    headers: { "Content-Type": "image/png" },
  });
}

Métodos HTTP

Além da função GET, você pode exportar uma função com o nome de qualquer método HTTP. Assim, quando uma requisição for recebida, o Astro irá checar o método e chamar a função correspondente.

Também é possível exportar uma função ALL para corresponder a todos os métodos que já não tenham suas respectivas funções exportadas. Se houver uma requisição sem método correspondente, ela será redirecionada para a sua página de 404.

src/pages/methods.json.ts
export const GET: APIRoute = ({ params, request }) => {
  return new Response(JSON.stringify({
      message: "Isso foi um GET!"
    })
  )
}


export const POST: APIRoute = ({ request }) => {
  return new Response(JSON.stringify({
      message: "Isso foi um POST!"
    })
  )
}


export const DELETE: APIRoute = ({ request }) => {
  return new Response(JSON.stringify({
      message: "Isso foi um DELETE!"
    })
  )
}


export const ALL: APIRoute = ({ request }) => {
  return new Response(JSON.stringify({
      message: `Isso foi um ${request.method}!`
    })
  )
}
Receitas relacionadas

request

No modo SSR, a propriedade request retorna um objeto Request completamente utilizável que se refere a requisição atual. Isso permite que você aceite dados e cheque cabeçalhos:

src/pages/test-post.json.ts
export const POST: APIRoute = async ({ request }) => {
  if (request.headers.get("Content-Type") === "application/json") {
    const body = await request.json();
    const name = body.name;
    return new Response(JSON.stringify({
      message: "Seu nome é: " + name
    }), {
      status: 200
    })
  }
  return new Response(null, { status: 400 });
}

Redirecionamentos

O contexto do endpoint exporta um utilitário redirect() similar ao Astro.redirect:

src/pages/links/[id].js
import { getLinkUrl } from '../db';


export async function GET({ params, redirect }) {
  const { id } = params;
  const link = await getLinkUrl(id);


  if (!link) {
    return new Response(null, {
      status: 404,
      statusText: 'Não encontrado'
    });
  }


  return redirect(link, 307);
}