Criar APIs REST e GraphQL

Execute uma API como uma function que lê o SQL Database, grava pela Azion API, guarda respostas de lista em cache e reporta latência e erros.

Última atualização

Ver como Markdown Configurar agente

Um time de desenvolvimento constrói o backend REST ou GraphQL que os clientes web e mobile dele chamam, com usuários em várias regiões e sem nenhum servidor que ele queira operar. A API guarda os registros em um banco de dados relacional, a maioria das chamadas lê e algumas chamadas gravam. Esta página implanta uma function que implementa todos os endpoints de uma API REST, lê os registros do SQL Database, grava-os pela Azion API e mantém a resposta de lista em cache por pouco tempo. O resultado é medido pelo tempo de resposta da API por região, pela taxa de erros sob carga e pelo tempo entre uma mudança de código e a produção.

Este caso de uso não cobre APIs que reagem a eventos em vez de chamadores, que Criar APIs orientadas a eventos cobre, nem controles de segurança na frente de uma API que roda em outro lugar, que Proteger APIs públicas contra abuso cobre.

Pré-requisitos

  • A Azion CLI instalada, com o seu personal token salvo. Para configurá-la, consulte Primeiros passos com a Azion CLI.
  • SQL Database habilitado na sua conta e a permissão Edit SQL Database. O produto está em Preview, então solicite acesso pelo Technical Support.
  • Um personal token para as chamadas ao banco de dados, separado do que a CLI usa, porque a function o armazena. Para criar um, consulte Personal tokens.
  • Node.js e um gerenciador de pacotes, que a CLI usa para construir o projeto.
  • Os nomes que esta página usa: tasks-api para o banco de dados e para o cache de respostas, /api/tasks para o caminho da API, TASKS_DB_ID e TASKS_SQL_TOKEN para as variáveis de ambiente da function e api.example.com para o domínio. O deploy exibe um domínio xxxxxxxxxx.map.azionedge.net; para servir a API no seu próprio domínio, consulte Adicione um domínio a um workload. Substitua cada valor pelo seu em todos os passos.

Produtos necessários

A API precisa deO que significaProdutoDocumentado em
Endpoints que rodam sem nenhum servidor para operarUma function, implantada com a Azion CLI, que a aplicação executa em toda requisiçãoFunctionsFaça o deploy de uma function com a Azion CLI
Registros que todos os endpoints leem e gravamLeituras de uma read replica do banco de dados dentro da function, e gravações pela Azion APISQL DatabaseGrave linhas no SQL Database a partir de uma function
Uma resposta de lista que não é reconstruída a cada chamadaUma resposta que a function guarda com a Cache API do runtime, sob um max-ageCacheArmazene em cache a resposta de uma function com a Cache API
Latência e erros no domínio da APIOs dashboards Requests e Status Codes filtrados pelo domínio, e as invocações de FunctionsReal-Time MetricsDashboards de Build

Arquitetura de referência

Esta página constrói a API de serviço único sobre o SQL Database: uma function implementa todos os endpoints e lê e grava um banco de dados no SQL Database.

Leia o diagrama da function para fora. Toda requisição que a aplicação recebe executa a mesma function, então a function é o único lugar que conhece todos os endpoints. A partir dela, os caminhos se dividem pelo que o endpoint faz: uma resposta que todo cliente pode compartilhar vai para o Cache, uma leitura vai para uma réplica do banco de dados e uma gravação vai para a instância principal. O KV Store fica ao lado do banco de dados para valores lidos por chave, como uma sessão, e o design funciona sem ele. O Real-Time Metrics lê o que a aplicação registra e não muda nada no caminho da requisição.

Fluxo de dados

  1. A requisição de um cliente chega ao workload no domínio da API, que a entrega à aplicação, e uma regra da aplicação executa a function da API.
  2. A function compara o método e o caminho. Um caminho fora de /api/tasks responde 404.
  3. Um GET da lista de tarefas é respondido pela cópia que a function guardou no Cache. Quando não existe cópia, a function lê as linhas e guarda a nova resposta por 60 segundos.
  4. Um GET de uma tarefa abre uma conexão com uma read replica do banco de dados com Database.open, que recebe o nome do banco de dados e nenhum token, então os dados de que uma leitura precisa ficam dentro da Azion.
  5. Um POST ou um DELETE envia o statement ao endpoint de query do banco de dados na Azion API, com o personal token que a function lê de uma variável de ambiente, porque a instância principal é a única que aplica gravações. As réplicas passam a ter a mudança em seguida.
  6. Depois de uma gravação, a function apaga a resposta de lista guardada, para que a requisição de lista seguinte leia as linhas de novo.

Componentes

  • aplicação: o Platform Resource que recebe as requisições da API no domínio dela e as encaminha para a function com uma regra do Rules Engine.
  • Functions: uma function implementa todos os endpoints. Um deploy substitui o código de todos os endpoints juntos, e é isso que faz da API uma unidade, então um deploy, um rollback ou uma mudança de schema chega a todos os endpoints no mesmo momento.
  • SQL Database: guarda os dados relacionais da API. Uma function lê por uma read replica sem token, e as gravações vão para a instância principal pela Azion API com um personal token.
  • KV Store: guarda sessões e configurações lidas por chave, uma opção de design. Ele tem consistência eventual e não tem compare-and-set, então carrega valores que toleram um atraso curto, não os registros da API.
  • Cache: guarda as respostas que todo cliente pode compartilhar, como uma lista ou uma consulta, para que uma chamada repetida pule a leitura no banco de dados.
  • Real-Time Metrics: reporta o tempo de requisição e os status codes da API por domínio e o número de vezes que a function rodou.

Outros designs para este caso de uso

  • API de serviço único sobre um banco de dados externo: para times cujos dados já estão em um banco de dados gerenciado como Neon, MongoDB Atlas, TiDB ou Turso, que uma function consulta pelo driver serverless ou pela API HTTP dele. Toda chamada fora do cache chega ao banco de dados externo, então a latência e a disponibilidade dele entram nos fluxos de requisição e de falha.
  • API de microsserviços sobre Functions: para times que dividem uma API em serviços de times diferentes, cada um uma function com o seu próprio armazenamento, implantada e versionada de forma independente. Uma regra do Rules Engine encaminha cada prefixo de caminho para o seu serviço e os serviços chamam uns aos outros por HTTP pelas mesmas regras, então um deploy muda um serviço e deixa os outros na versão que tinham.

Configure o banco de dados de tarefas

A API de tarefas guarda os registros em uma tabela de um banco de dados chamado tasks-api. A function lê o banco de dados pelo nome e grava nele pelo identificador, então esta seção cria o banco de dados pela API, cuja resposta de criação retorna esse identificador. O Azion Console também pode criar o banco de dados e executar o statement na aba Editor, como Crie e gerencie bancos de dados mostra.

Para criar o banco de dados:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/sql/databases \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token <personal-token>' \
05 --header 'Content-Type: application/json' \
06 --data '{"name": "tasks-api"}'

A API responde 202. Guarde data.id: é o identificador do banco de dados em que a function grava.

{"state":"pending","data":{"id":<database-id>,"name":"tasks-api","status":"creating","active":true,...}}

O provisionamento leva cerca de 15 segundos. Envie GET /v4/workspace/sql/databases/<database-id> até que status mostre created e, depois, crie a tabela e duas linhas para ler de volta. completed é uma coluna inteira, 0 ou 1, porque a function a lê como número:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/sql/databases/<database-id>/query \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token <personal-token>' \
05 --header 'Content-Type: application/json' \
06 --data {"statements": [
07 "CREATE TABLE IF NOT EXISTS tasks (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, completed INTEGER NOT NULL DEFAULT 0);",
08 "INSERT INTO tasks (title, completed) VALUES ('\''Write the API spec'\'', 0);",
09 "INSERT INTO tasks (title, completed) VALUES ('\''Deploy the API'\'', 1);"
10 ]}

A API responde 200 com "state": "executed" e uma entrada por statement em data. Um statement que falha também responde 200, com error no lugar de results na entrada dele, então verifique cada entrada:

{"state":"executed","data":[{"results":{"columns":[],"rows":[],"rows_read":0,"rows_written":0,...}},...]}

O banco de dados tasks-api tem a tabela tasks e duas linhas.

Configure as credenciais de gravação da function

Uma function lê um banco de dados por uma réplica somente leitura, e um statement que grava falha nela com attempt to write a readonly database. Por isso, a function da API envia as gravações para a Azion API e precisa de dois valores para isso: o identificador do banco de dados e um personal token. Armazene os dois como Grave linhas no SQL Database a partir de uma function descreve, com os nomes de chave da API:

Shell
01azion create variables --key TASKS_DB_ID --value <database-id> --secret false
02azion create variables --key TASKS_SQL_TOKEN --value <personal-token> --secret true

Uma variável só chega à function depois de um deploy, então crie as duas antes do deploy feito na configuração da function da API.

Configure a function da API

A function da API é um handler ES Modules que implementa todos os endpoints sob /api/tasks. Ela lê com a classe Database do global Azion.Sql. As gravações dela seguem Grave linhas no SQL Database a partir de uma function, e a lista dela segue Armazene em cache a resposta de uma function com a Cache API, com estes valores:

  • Gravações: writeTasks envia um statement por chamada, com TASKS_DB_ID e TASKS_SQL_TOKEN, e lança um erro quando a requisição ou o statement falha.
  • Cache da lista: o cache tasks-api, a chave <origin>/api/tasks e max-age=60. Todo POST e todo DELETE apaga essa chave depois da gravação, então os 60 segundos só limitam por quanto tempo uma lista fica desatualizada quando essa exclusão não roda.
Crie o projeto

Execute azion init, insira tasks-api como nome e selecione o preset Javascript e o template Hello World, como Faça o deploy de uma function com a Azion CLI mostra. Depois, vá para o diretório do projeto.

Substitua o handler

Substitua o conteúdo de index.js, o entrypoint que o build lê, pelo código abaixo.

Implante o projeto

Execute azion deploy no diretório do projeto. O comando constrói o projeto, cria a aplicação e a function, instancia a function e exibe o domínio que a serve.

JavaScript
01const { Database } = Azion.Sql;
02
03const DATABASE_NAME = 'tasks-api';
04const CACHE_NAME = 'tasks-api';
05const LIST_MAX_AGE = 60;
06
07function json(body, status = 200, headers = {}) {
08 return new Response(JSON.stringify(body), {
09 status,
10 headers: { 'content-type': 'application/json', ...headers },
11 });
12}
13
14// Reads come from a read replica. Integer parameters bind; string parameters are refused.
15async function readTasks(id) {
16 const connection = await Database.open(DATABASE_NAME);
17 const rows = id === undefined
18 ? await connection.query('SELECT id, title, completed FROM tasks ORDER BY id')
19 : await connection.query('SELECT id, title, completed FROM tasks WHERE id = ?', [id]);
20 const tasks = [];
21 let row = await rows.next();
22 while (row) {
23 tasks.push({ id: row.getValue(0), title: row.getValue(1), completed: row.getValue(2) === 1 });
24 row = await rows.next();
25 }
26 return tasks;
27}
28
29// Writes go to the main instance through the Azion API. A failed statement still answers 200.
30async function writeTasks(statement) {
31 const response = await fetch(
32 `https://api.azion.com/v4/workspace/sql/databases/${Azion.env.get('TASKS_DB_ID')}/query`,
33 {
34 method: 'POST',
35 headers: {
36 Accept: 'application/json',
37 Authorization: `Token ${Azion.env.get('TASKS_SQL_TOKEN')}`,
38 'Content-Type': 'application/json',
39 },
40 body: JSON.stringify({ statements: [statement] }),
41 },
42 );
43 if (!response.ok) {
44 throw new Error(`Azion API answered ${response.status}`);
45 }
46 const entry = (await response.json()).data[0];
47 if (entry.error) {
48 throw new Error(entry.error);
49 }
50 return entry.results;
51}
52
53// The query endpoint takes SQL strings, so a text value is quoted and its quotes doubled.
54function sqlText(value) {
55 return `'${String(value).replaceAll("'", "''")}'`;
56}
57
58export default {
59 async fetch(request) {
60 const url = new URL(request.url);
61 const match = url.pathname.match(/^\/api\/tasks(?:\/(\d+))?$/);
62 if (!match) {
63 return json({ error: 'Not found' }, 404);
64 }
65 const id = match[1] === undefined ? undefined : Number(match[1]);
66 const cache = await caches.open(CACHE_NAME);
67 const listKey = `${url.origin}/api/tasks`;
68
69 try {
70 if (request.method === 'GET' && id === undefined) {
71 const cached = await cache.match(listKey);
72 if (cached) {
73 return cached;
74 }
75 const list = json(await readTasks(), 200, {
76 'cache-control': `max-age=${LIST_MAX_AGE}`,
77 'x-tasks-cached-at': new Date().toISOString(),
78 });
79 await cache.put(listKey, list.clone());
80 return list;
81 }
82 if (request.method === 'GET') {
83 const [task] = await readTasks(id);
84 return task ? json(task) : json({ error: 'Task not found' }, 404);
85 }
86 if (request.method === 'POST' && id === undefined) {
87 const { title, completed = false } = await request.json();
88 if (typeof title !== 'string' || title.length === 0) {
89 return json({ error: 'title is required' }, 400);
90 }
91 const results = await writeTasks(
92 `INSERT INTO tasks (title, completed) VALUES (${sqlText(title)}, ${completed ? 1 : 0}) RETURNING id`,
93 );
94 await cache.delete(listKey);
95 return json({ id: results.rows[0][0], title, completed: Boolean(completed) }, 201);
96 }
97 if (request.method === 'DELETE' && id !== undefined) {
98 const results = await writeTasks(`DELETE FROM tasks WHERE id = ${id}`);
99 await cache.delete(listKey);
100 return results.rows_written > 0
101 ? json({ message: 'Task deleted' })
102 : json({ error: 'Task not found' }, 404);
103 }
104 return json({ error: 'Method not allowed' }, 405);
105 } catch (error) {
106 console.log(error.message);
107 return json({ error: 'Internal error' }, 500);
108 }
109 },
110};

O código toma mais três decisões:

  • As leituras ficam dentro da Azion. Database.open não precisa de token, e o parâmetro ? carrega o ID da tarefa como inteiro, que a réplica vincula. Passar uma string JavaScript como parâmetro falha com unknown variant `String` .
  • A exclusão reporta uma tarefa inexistente. rows_written conta as linhas que o statement gravou, então 0 significa que nenhuma tarefa tinha aquele ID.
  • A cópia da lista carrega o próprio timestamp. x-tasks-cached-at é definido uma única vez, quando a function guarda a resposta, então duas respostas com o mesmo valor vieram da mesma cópia guardada.

A API responde no domínio que o deploy exibiu, todos os endpoints rodam na function, e a resposta de lista fica em cache por 60 segundos. O primeiro deploy pode levar vários minutos para responder em todas as localidades.

Verifique a configuração

Cada verificação chama a API no domínio dela. Um primeiro deploy que ainda não responde ainda está se propagando; espere alguns minutos e tente de novo.

  • O endpoint de lista lê o banco de dados. Requisite a lista:

    curl -i https://api.example.com/api/tasks

    A resposta traz 200 e as duas linhas que a tabela guarda:

    [{"id":1,"title":"Write the API spec","completed":false},{"id":2,"title":"Deploy the API","completed":true}]

  • A lista vem da cópia em cache. Repita a requisição em até 60 segundos. O header x-tasks-cached-at traz o mesmo valor da primeira resposta.

  • Uma gravação chega ao banco de dados. Crie uma tarefa:

    Shell
    01curl -i -X POST https://api.example.com/api/tasks \
    02 -H "Content-Type: application/json" \
    03 -d '{"title": "Review the logs"}'

    A resposta traz 201 e o ID que o banco de dados atribuiu:

    {"id":3,"title":"Review the logs","completed":false}

    Um 500 aqui significa que a gravação falhou. Leia a mensagem que a function registrou no log, como Consultar logs de console de uma function mostra: Azion API answered 401 aponta para o valor de TASKS_SQL_TOKEN, e uma mensagem de erro do banco de dados aponta para o statement.

  • Uma gravação atualiza a lista. Requisite a lista de novo. A resposta traz um novo valor de x-tasks-cached-at e três tarefas.

  • Uma tarefa inexistente responde 404. Apague a mesma tarefa duas vezes:

    curl -X DELETE https://api.example.com/api/tasks/3

    A primeira chamada responde {"message":"Task deleted"}, e a segunda responde 404 com {"error":"Task not found"}.

Medindo resultados

MétricaOnde lerComo fica quando funciona
Tempo de resposta da API por regiãoAverage Request Time no dashboard Requests do Real-Time Metrics, filtrado por Host pelo domínio da API e por Country. Consulte Filtre um dashboard de Real-Time MetricsComparável entre os países de onde os seus clientes chamam e estável conforme o tráfego cresce
Taxa de erros sob cargaHTTP Status Codes 5XX no dashboard Status Codes, filtrado pelo domínio da API. Consulte Dashboards de BuildNenhuma série de 500 subindo com o volume de requisições; uma subida aponta para gravações que falharam, que a function registra no log
Com que frequência o código da API rodaTotal Invocations na aba Functions, série Edge Application Invocations. Consulte Dashboards de BuildAcompanha o número de requisições da API, já que toda requisição executa a function
Tempo entre uma mudança de código e a produçãoO log de deploy que azion deploy indica no Azion Console. Consulte Como a Azion CLI funcionaCada deploy termina, e o novo código responde assim que se propaga, em cerca de dois minutos para um deploy depois do primeiro

Boas práticas

  • Leia pela réplica e grave pela API. Database.open chega a uma read replica sem token e recusa gravações. Enviar as leituras para a API gasta o personal token em toda chamada e adiciona uma requisição que a réplica responde diretamente. Para como a instância principal e as réplicas dividem o trabalho, consulte Como o SQL Database funciona.

  • Verifique cada statement, não o status HTTP. Um statement que falha retorna 200 com error na entrada dele. Um cliente que lê só o status reporta um insert que falhou como sucesso, e o registro nunca é gravado:

    JavaScript
    01const entry = (await response.json()).data[0];
    02if (entry.error) throw new Error(entry.error);

  • Dê à function um token só dela, com uma expiração planejada. Um personal token expira na data escolhida quando ele é criado, e todas as gravações falham a partir desse momento. Um token usado só pela function pode ser substituído e implantado de novo sem mexer no token da CLI. Para as opções de expiração, consulte Personal tokens.

  • Nunca monte um statement a partir do texto bruto da requisição. O endpoint de query recebe strings SQL, então um título que carrega uma aspa muda o statement que o banco de dados executa. Coloque os valores de texto entre aspas e duplique as aspas deles, como sqlText faz, e valide cada campo antes que ele chegue a um statement.

  • Guarde em cache só o que todo cliente pode ler. Uma resposta guardada com a Cache API é devolvida a qualquer requisição seguinte com a mesma chave. Guarde em cache respostas de lista e de consulta que são as mesmas para todo cliente, e nunca uma resposta construída a partir das credenciais de um cliente.

Guias deste caso de uso

Grave linhas no SQL Database a partir de uma functionArmazena as credenciais do banco de dados como variáveis de ambiente e envia as gravações que a function da API faz.Armazene em cache a resposta de uma function com a Cache APIGuarda a resposta de lista sob um max-age e a apaga depois de cada gravação.