Compartilhamento de dados entre sistemas

Autenticação

Cada solicitação de API enviada de um aplicativo de terceiros para o site do Centro de Comando será autenticada e autorizada como se um usuário real estivesse usando o software. As permissões do grupo do usuário associado à solicitação da API determinam quais campos e funcionários cada solicitação da API pode exibir e / ou editar.

Para usar a API, cada usuário deve ter uma ou mais chaves de API secretas que identifiquem esse usuário para a API. A chave secreta da API é um número de 160 bits expresso em formato hexadecimal. Este é um número astronomicamente grande de chaves exclusivas, o que significa que adivinhar uma chave de API é quase impossível.

Para gerar uma chave de API para um determinado usuário, os usuários devem fazer login e clicar em seu nome no canto superior direito de qualquer página para acessar o menu de contexto do usuário. Haverá uma opção "Chaves de API" nesse menu para ir para a página.

Se uma chave de API desconhecida for usada repetidamente, a API desativará o acesso por um período de tempo. Os usuários ainda poderão fazer login no site do Command Center durante esse período. Quando a API está desabilitada, ela envia de volta uma resposta HTTP 403 Proibida a qualquer solicitação recebida.

No nível HTTP, a chave da API é enviada pela autenticação básica HTTP. Use a chave secreta como nome de usuário e qualquer string aleatória para a senha.

Para obter mais informações sobre HTTP Basic Authentication, consulte este útil artigo da Wikipédia .

Fazendo pedidos

• Todas as solicitações feitas para nossas APIs devem ser enviadas por HTTPS. O certificado SSL usado para a conexão HTTPS é assinado e todas as implementações devem configurar sua camada SSL para verificá-lo.
• solicitações são feitas para um URL que começa com: https://api.baseline.info/
• Solicitações de API podem ser limitadas se o Baseline considerar que elas são muito frequentes. As implementações devem estar sempre prontas para uma resposta 503 Serviço indisponível.
• As implementações também devem estar sempre prontas para a perda geral de pacotes da Internet, resultando em conexões interrompidas sem resposta HTTP.
• Cada funcionário tem um ID de funcionário imutável que é único dentro de uma única empresa que você pode usar para fazer referência ao funcionário.
• Todas as solicitações devem estar em UTF-8.

Códigos de Status HTTP

Cada pedido inclui um código de status HTTP com o resultado. O código de status deve ser examinado antes da resposta.

Códigos de status bem sucedidos (2xx)

• 200 OK - O pedido foi bem sucedido.
• 201 Created - O recurso foi criado com sucesso. Confirma um sucesso ao criar um novo funcionário, solicitação de folga, etc.

Códigos de status de erro do cliente (4xx)

• 400 Solicitação incorreta - a solicitação era inválida ou não pôde ser entendida pelo servidor. O reenvio da solicitação provavelmente resultará no mesmo erro.
• 401 Não autorizado - Sua chave de API está faltando.
• 403 Proibido - O aplicativo está tentando executar uma ação que não tem privilégios para acessar. Verifique se sua chave de API pertence a um usuário habilitado com as permissões necessárias.
• 404 Not Found - O recurso não foi encontrado com o identificador fornecido. O URL fornecido não é uma API válida ou o ID do objeto especificado na solicitação é inválido.
• 406 Não Aceitável - A solicitação contém referências a campos inexistentes.
• 409 Conflito - A solicitação tenta criar uma duplicata. Para funcionários, e-mails duplicados não são permitidos. Para listas, valores duplicados não são permitidos.
• 429 Limite Excedido - A conta atingiu seu limite de funcionários. Nenhum funcionário adicional pode ser adicionado.

Códigos de status de erro do servidor (5xx)

• 500 Internal Server Error - O servidor encontrou um erro ao processar sua solicitação e falhou.
• 502 Erro de gateway - O balanceador de carga ou servidor da web teve problemas para se conectar ao aplicativo Command Center. Por favor, tente o pedido novamente.
• 503 Service Unavailable - O serviço está temporariamente indisponível. Por favor, tente o pedido novamente.

Você pode testar seu código no futuro usando os seguintes intervalos:

• 200-299 como sucesso
• 400–499 como erros de solicitação do cliente
• 500–599 como erros do servidor

Usuários do sistema e usuários do Passport

Compatibilidade entre versões

Toda tentativa será feita para fazer somente alterações compatíveis à API. Para ajudar nesse esforço, os consumidores da API devem ignorar todas as tags e atributos XML que não reconhecem.

A API suportará vários números de versão principais da API. Atualmente, a única versão é "v1". Se uma alteração importante na API for necessária, criaremos um novo número de versão principal e comunicaremos a alteração aos nossos parceiros. Manteremos a API "v1" existente por um período de tempo razoável.