Migrar para o endereço da API

As integrações mais antigas chamam a API no endereço principal do Sursa, o que as pessoas abrem no navegador, por exemplo https://app.sursa.com/v1/…. Agora a API também tem um endereço próprio, https://api.sursa.com na nuvem ou https://api.<your domain> na sua instalação. Ele foi feito para integrações: escala horizontalmente atrás de um balanceador de carga e não atende nada além da API.

Você não é obrigado a migrar. O endereço principal continua atendendo /v1 para as integrações existentes, sem data de término e sem redirecionamento. Migre quando for conveniente, para ter as vantagens do endereço da API, e use-o em todas as integrações novas.

O que continua igual

Os caminhos, parâmetros, campos, códigos de erro e eventos: GET /v1/cards é a mesma requisição nos dois endereços.
As chaves de API. As mesmas chaves kb_ e kbsrc_ funcionam nos dois endereços, com a mesma função, os mesmos escopos e o mesmo perfil de dados.
As chaves de idempotência, os limites de taxa e as cotas. As requisições nos dois endereços contam para as mesmas cotas da organização.
Os webhooks. As entregas, as assinaturas e os segredos não dependem do endereço que você chama.
Os links nas respostas. O doc_url de um erro aponta para este portal, e o cabeçalho Link da página de uma lista aponta para o endereço da API, qualquer que seja o endereço que você chama.

O que é diferente no endereço da API

No endereço principal	No endereço da API
Todos os endpoints do aplicativo web, inclusive os internos	Só os endpoints da referência da API pública. Qualquer outro caminho responde `404` com o código `api.not_found`.
Uma chave em `X-API-Key` ou `Authorization`, ou um cookie de sessão do navegador	Uma chave ou um token de acesso OAuth, de preferência em `Authorization: Bearer`. Os cookies são ignorados.
`GET /auth/me`	`GET /v1/me`. Os caminhos em `/auth/` não são atendidos.
O modo “View as” (ver a base como um perfil de dados a vê) por cookie	O cabeçalho `X-View-As`, para chaves com a função `admin`.

| Um servidor ou um conjunto fixo | Vários servidores atrás de um balanceador de carga. |

A última linha só importa em um caso: uma resposta transmitida de POST /v1/chat. Um stream interrompido continua a partir de Last-Event-ID apenas no servidor que escreve a resposta. Se a sua integração retoma streams, dê a cada pergunta um request_id, para que uma nova tentativa em outro servidor receba a resposta salva, e não uma segunda resposta. Veja Retomar um stream interrompido.

Antes de migrar

Verifique se todas as chamadas são públicas. Liste os caminhos que a sua integração chama e procure cada um na referência da API, ou compare-os com a especificação do novo endereço:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Um caminho que não aparece na referência pública pertence ao aplicativo web. Ele continua funcionando no endereço principal, mas não é atendido no endereço da API, e o formato dele não é um compromisso público. Substitua-o por um endpoint público ou mantenha essa parte da integração no endereço principal e diga ao seu contato no Sursa do que você precisa.

Verifique como você se autentica. Se a integração faz login com a senha de um usuário e um cookie de sessão, passe-a primeiro para uma chave de API. Se ela envia X-API-Key, mudar para Authorization: Bearer é recomendado, mas não obrigatório.

Verifique a sua rede. Libere o HTTPS de saída para o novo nome do host no seu firewall e nos seus proxies.

Migrar passo a passo

Transforme a URL base em uma configuração da sua integração, se ela ainda não for.

Teste o novo endereço com uma requisição de leitura:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Execute a suíte de testes da sua integração no novo endereço, com uma chave de teste e uma coleção de teste.
Mude uma parte do tráfego, por exemplo um worker ou um ambiente, e observe 404 api.not_found, 401 e 5xx nos seus logs. Toda resposta traz X-Request-Id; guarde-o com os seus logs.
Mude o restante. Mantenha a URL base antiga na sua configuração por um tempo, para poder voltar em segundos.

O que verificar depois da migração

GET /v1/health no novo endereço retorna a mesma version que no antigo.
Os cabeçalhos RateLimit estão presentes nas respostas. Se a sua integração reduz o próprio ritmo com base em X-RateLimit-*, ela pode continuar fazendo isso: os dois conjuntos são enviados. Veja Limites de taxa e cotas.
Se a sua integração funciona em um navegador, ela não precisa mais do seu próprio proxy para CORS: o endereço da API permite requisições de qualquer origem, sem cookies.