Endereço da API e ambientes

A API do Sursa tem um endereço próprio, separado do endereço que as pessoas usam para abrir o Sursa no navegador. Todos os caminhos começam com /v1.

Onde o Sursa funciona	Endereço da API	Este portal
Nuvem do Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Sua própria instalação	`https://api.<your domain>`, conforme configurado pelo seu administrador	`/developers/` no endereço da API
Sua instalação sem um endereço de API separado	o endereço principal da instalação	`/developers/` no endereço principal

O endereço da API só atende a API: nele não há página de login, cookies nem interface web. Toda requisição é autenticada com uma chave de API ou um token de acesso OAuth. O endereço pode ser atendido por vários servidores atrás de um balanceador de carga; sua integração não precisa saber quantos são.

As integrações que chamam a API no endereço principal (por exemplo, https://app.sursa.com/v1) continuam funcionando. Veja Migrar para o endereço da API para conhecer as poucas diferenças e fazer a migração passo a passo.

URL base

Monte todas as requisições a partir de uma única URL base na sua configuração, para que o mesmo código funcione em qualquer ambiente:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Use somente HTTPS e mantenha a chave fora dos logs das requisições que você faz.

Versão e especificação

GET /v1/health informa se o endereço está no ar e retorna a versão do Sursa que o atende. Ele responde sem chave, então você pode usá-lo no monitoramento:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Essa é a versão do lançamento do Sursa, não da API. A versão da API é o info.version da especificação dela. A especificação OpenAPI 3.1 da API é publicada no mesmo endereço, sem autenticação:

Caminho	Conteúdo
`GET /openapi.json`	A especificação pública, com este endereço em `servers`.
`GET /v1/openapi-public.json`	A mesma especificação. Aceita `ETag` e `If-None-Match`.

Use-a para gerar um cliente, para importar a API em uma ferramenta como o Postman ou para verificar no CI se a sua integração usa só operações da versão esperada. A referência da API deste portal é gerada a partir do mesmo arquivo.

Testes

O Sursa não tem um modo de teste separado: toda requisição com uma chave atua sobre os dados reais da organização dela. Para desenvolver e testar com segurança:

Crie uma chave separada para o desenvolvimento, com a função e os escopos mais restritos de que o trabalho precisa.
Grave em uma coleção dedicada, por exemplo sandbox, que só a sua equipe pode ver, e exclua-a quando terminar.
Se a sua empresa tem uma organização ou instalação separada do Sursa para testes, aponte a URL base e a chave para ela. Nada mais muda no seu código.
Torne as novas tentativas seguras desde o início: envie uma Idempotency-Key em cada POST e PATCH.

O console Testar, em cada página de endpoint da referência da API, envia requisições reais com uma chave que você cola nele. A chave fica na memória da aba do navegador e é enviada só para o endereço da API.

Requisitos de rede

HTTPS de saída (porta 443) dos seus servidores para o endereço da API.
Nas regras do firewall, libere o nome do host em vez de endereços IP fixos, quando a sua rede permitir: os servidores atrás do endereço podem mudar conforme a capacidade aumenta.
Os aplicativos de navegador podem chamar a API diretamente: as respostas permitem qualquer origem (Access-Control-Allow-Origin: *) sem cookies. Lembre-se de que uma chave usada em um navegador fica visível para o usuário desse navegador.