Scripted REST APIs
O recurso REST API com script permite que os desenvolvedores de aplicações criem APIs de serviço web personalizadas.
Você pode definir endpoints de serviço, parâmetros de consulta e cabeçalhos para uma REST API com script, bem como scripts para gerenciar a solicitação e a resposta.
REST APIs com script geralmente seguem a arquitetura REST, mas você pode personalizá-las para usar convenções diferentes. REST APIs com script são definidas usando o formulário de serviço REST com script encontrado em Serviços da Web com Script → REST APIs com script .
REST API com script
REST API com script têm o seguinte formato:
https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>
- <instance.service-now.com>Caminho para ServiceNow Instância em que os usuários acessam a REST API com script.
- <name_space>: Para serviços web no escopo global, o espaço do nome é o valor da propriedade glide.appcreator.company.code. Para serviços web em uma aplicação com escopo, o espaço do nome é o nome do escopo, como x_company_appname. Para obter informações adicionais sobre espaços de nome, consulte Escopo da aplicação .
- <version>: Opcional. Versão do endpoint a ser acessado se a API usar controle de versões, como v1 . Você pode acessar a versão padrão de uma API com controle de versão especificando o URI sem um número de versão.
- <api_id>Valor do ID DA API Campo no formulário Serviço REST com script. Por padrão, este valor é baseado no nome do serviço.
- <relative_path>Caminho relativo definido para o recurso no formulário Serviço REST com script. Especificar um caminho de recurso relativo permite que você tenha vários recursos usando o mesmo método HTTP, como GET, em um serviço web. Por exemplo, um recurso pode especificar o caminho
(id)Quando o serviço web tem apenas um recurso GET, ou/user/e./message/quando o serviço web tem recursos diferentes para solicitar registros de usuário e mensagem.
Controle de versões DA REST API com script
REST API com script podem incluir um número de versão, como /api/management/v1/table/ . Os números de versão identificam a versão do endpoint que um URI acessa. Ao especificar um número de versão em seus URIs, você pode testar e implantar mudanças sem afetar as integrações existentes.
Versão da API padrão
Uma versão pode ser marcada como padrão. Especificar uma versão padrão permite que os usuários acessem essa versão usando um endpoint REST com script sem um número de versão. Se nenhuma versão estiver marcada como padrão, a versão mais recente será usada como padrão.
Recursos da REST API com script
Um recurso de REST API com script é equivalente a um endpoint REST. Ele define o método HTTP a ser executado, o script de processamento e todas as configurações de substituição da API primária. Você pode definir um ou mais recursos por API.
Parâmetros de consulta da REST API com script
Os parâmetros de consulta definem valores que os usuários solicitantes podem passar em uma solicitação. Ao criar uma REST API com script, você pode especificar quais parâmetros estão disponíveis e quais são obrigatórios para cada solicitação. Você também pode associar um parâmetro de consulta a vários recursos.
Parâmetros de solicitação de acesso em scripts usando o objeto de solicitação QueryParams campo.
Funções da REST API com script
Formatos de solicitação e resposta
Por padrão, todos os recursos em uma API são compatíveis com os seguintes formatos de solicitação e resposta: aplicativo/json, aplicativo/xml e texto/xml. Você pode substituir os formatos padrão no nível da API. Os novos formatos se aplicam a todos os recursos pertencentes à API, a menos que um recurso individual substitua os padrões.
Segurança de REST API com script
Você pode configurar suas REST APIs com script com o nível de segurança necessário. De APIs/endpoints públicos que não exigem segurança a APIs/endpoints altamente seguros que exigem autenticação do usuário com controle de acesso rígido a todos os recursos.
Use o recurso de política de acesso à API para controlar o método de autenticação das APIs. Para obter mais informações, consulte API access policy.
Controles de acesso da REST API com script
ACLs (Access Control Lists, listas de controle de acesso) definem critérios, como as funções necessárias e as condições que um usuário deve atender para acessar uma REST API com script ou endpoint. Um usuário solicitante deve satisfazer pelo menos uma das ACLs. Não é necessário satisfazer todas as ACLs selecionadas. Você pode definir uma ACL única para uma REST API inteira ou para um endpoint individual.
Ao definir uma ACL de REST API com script, ela deve ter Tipo valor Endpoint REST .
Para obter informações adicionais sobre ACLs, consulte Regras da lista de controle de acesso e. Configure um recurso de REST API com script para exigir uma ACL.
Matriz de segurança da REST API com script
Há várias configurações de segurança possíveis para REST APIs com script. Use esta tabela para identificar a configuração de segurança da REST API com script que melhor atende às suas necessidades e os valores de campo para implementar essa configuração.
| Configuração | REST API de Script | Recurso REST de script | ||
|---|---|---|---|---|
| ACLs Padrão | Requer autenticação | Requer autorização de ACL | ACLs | |
| O recurso é público. Nenhuma autenticação ou ACL é necessária. | Qualquer valor | Falso(a) | Qualquer valor | Qualquer valor |
| O recurso requer somente autenticação básica. Nenhuma ACL é necessária. | Qualquer valor | Verdadeiro(a) | Falso(a) | Qualquer valor |
| O recurso requer somente autenticação básica. ACL é obrigatória. | Nenhuma ACL selecionada | Verdadeiro(a) | Verdadeiro(a) | Nenhuma ACL selecionada |
| Uma ACL selecionada no registro de recurso é necessária. | Qualquer valor | Verdadeiro(a) | Verdadeiro(a) | Uma ou mais ACLs selecionadas |
| Uma ACL selecionada no registro da REST API com script é necessária. | Uma ou mais ACLs selecionadas | Verdadeiro(a) | Verdadeiro(a) | Nenhuma ACL selecionada |
Objetos de erro da REST API com script
REST APIs com script incluem objetos de erro que permitem responder a uma solicitação com uma mensagem de erro HTTP padrão quando ocorre um erro durante o processamento da solicitação. Você pode usar objetos de erro em recursos de REST API com script para alertar os clientes solicitantes sobre erros. Use objetos de erro para responder a solicitações de entrada, não para detectar erros no código do lado do servidor.
Formato de resposta de erro
O tipo de conteúdo da resposta depende do cabeçalho de aceitação da solicitação. Se o cabeçalho Aceitar especificar um formato incompatível, como imagem/jpeg, a resposta de erro usará JSON.
{
"error": {
"message": "My error message",
"detail": "My details"
},
"status": "failure"
}Suporte ao Automated Test Framework
. Automated Test Framework (ATF) oferece suporte a etapas de teste REST DE entrada. Você pode criar testes automatizados para REST APIs de entrada personalizadas que você cria. Criar testes para suas REST APIs personalizadas simplifica o teste de atualização e possibilita verificar se as modificações em uma REST API são compatíveis com versões anteriores. Consulte Administração de configurações da etapa de teste REST e. Configurações da etapa de teste REST do ATF .
Desenvolver treinamento
Em ServiceNow® Site do desenvolvedor, você pode encontrar treinamento para REST APIs com script .