Pular para o conteúdo
CHAMPREPCHAMPREPCHAMPREP Docs

API Gateway Visão geral

O éCHAMPREPAPI Gateway o ponto de entrada público para integrações de plataformas suportadas. Ele valida credenciais, verifica escopos e acesso ao serviço, aplica os controles de uso vigentes e encaminha as solicitações aceitas para o CHAMPREPserviço relevante.

URL base

Seção intitulada “URL base”
https://api.champrep.com/v1

As rotas públicas selecionadas são versionadas em /v1. Utilize a URL HTTPS completa em aplicativos de servidor e utilize a configuração de ambiente, em vez de espalhar a URL base pelo seu código.

Primeira solicitação autenticada

Seção intitulada “Primeira solicitação autenticada”

Crie uma chave com escopo em API Chaves, e, em seguida, passe-a como uma credencial de portador:

Terminal window
curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

Nunca coloque uma chave real no controle de código-fonte, em um pacote de navegador, em um binário móvel, em uma mensagem de suporte ou na documentação. Utilize um gerenciador de segredos do lado do servidor para integrações implantadas.

Convenções de solicitação

Seção intitulada “Convenções de solicitação”
  • Envie e aceite JSON, a menos que um endpoint descreva explicitamente outro tipo de mídia.
  • Utilize carimbos de data e hora ISO 8601 com um fuso horário explícito para valores de data e hora.
  • Codifique os valores do caminho e da consulta usando URL-encode.
  • Mantenha a credencial de portador no Authorization cabeçalho.
  • Trate os identificadores como strings opacas; não deduza seu formato nem os construa localmente.
  • Utilize as /v1 as rotas no Referência de pontos de extremidade do serviço.

O serviço oficial SDKspode utilizar rotas de compatibilidade do Gateway enquanto um serviço estiver sendo migrado para um serviço selecionado /v1 contrato. Essa camada de compatibilidade destina-se ao SDK; novas integrações diretas não devem copiar caminhos privados do back-end a partir do tráfego do navegador ou de componentes SDKinternos.

Envelopes de resposta

Seção intitulada “Envelopes de resposta”

Respostas bem-sucedidas compostas pelo Gateway seguem este formato:

{
  "success": true,
  "data": {}
}

Os erros de gateway apresentam este formato:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

Algumas respostas de serviços proxy mantêm seu envelope de dados específico do serviço. Sempre verifique primeiro o status HTTP e, em seguida, leia success, data, ou error quando disponível. Consulte erros, limites e novas tentativas para gestão portátil de erros.

Fluxo de autenticação e autorização

Seção intitulada “Fluxo de autenticação e autorização”

Cada solicitação de serviço é avaliada na seguinte ordem:

  1. O Gateway valida a chaveAPI e quaisquer restrições de IP configuradas.
  2. A janela de uso atual do Gateway está marcada.
  3. API Gateway é verificado para o plano e o perfil ativos.
  4. O acesso ao serviço de destino é verificado.
  5. O escopo da chave é comparado com a rota e o método HTTP.
  6. O serviço de destino aplica suas próprias verificações de função, organização, recurso e cota.

A 403 pode, portanto, significar que a chave é válida, mas que o escopo ativo, a função, o acesso ao serviço, o plano, a política da organização ou a permissão de recurso não permitem a operação.

Controle de versões

Seção intitulada “Controle de versões”

O primeiro segmento da URL é a APIversão principal. Campos de resposta adicionais e novos endpoints podem aparecer dentro de uma versão principal. As integrações devem ignorar campos desconhecidos e não devem se basear em campos não documentados ou na ordem dos campos.

Utilize GET /v1/version para obter informações sobre a versão pública do Gateway. Planeje migrações para uma versão principal futura de forma explícita, em vez de reescrever /v1 em tempo de execução.

Próximos passos

Seção intitulada “Próximos passos”