Scripted REST APIs

O recurso de API REST de 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.

As Scripted REST APIs geralmente seguem a arquitetura REST, mas você pode personalizá-las para usar convenções diferentes. Você define REST APIs com script usando o formulário Serviço REST com script encontrado em Scripted Web Services → Scripted REST APIs.

Figura 1. Formulário Serviço REST com script

Os vídeos a seguir oferecem informações adicionais sobre REST APIs de script:

• Scripted REST APIs – Design
• Scripted REST APIs – Implementação

URIs de Scripted REST API

Os URIs de Scripted REST API têm o seguinte formato:

https://<instance.service-now.com> /API/<name_space> /<version> /<api_id> /<relative_path>

Neste URI:

• <instance.service-now.com>: caminho para a instância ServiceNow em que os usuários acessam a REST API com script.
• <name_space>: para serviços Web no escopo global, o namespace é o valor da propriedade glide.appcreator.company.code. Para serviços Web em uma aplicação com escopo, o namespace é o nome do escopo, como x_company_appname. Para obter informações adicionais sobre namespaces, consulte Escopo da aplicação.
• <version>: Opcional. Versão do endpoint a ser acessada 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 campo ID de API 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/{id} e /message/{id} quando o serviço web tem recursos diferentes para solicitar registros de usuário e mensagem .

Controle de versões da Scripted REST API

Os URIs de Scripted REST API podem incluir um número de versão, como /api/management/v1/table/{tableName}. 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 de Scripted REST API

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 de Scripted REST API

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.

Acesse parâmetros de solicitação em scripts usando o campo queryParams do objeto de solicitação.

Funções de Scripted REST API

Para trabalhar com REST APIs de script, você deve ter a função de administrador de serviço web [web_service_admin]. Usuários com esta função podem ler, criar, modificar e excluir REST APIs de script e recursos de serviço web.

Nota:

Essas funções não são necessárias para acessar um endpoint de 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 da REST API com script

Você pode configurar suas REST APIs com script com o nível necessário de segurança. De APIs/endpoints públicos que não exigem segurança a APIs/endpoints altamente seguros que exigem autenticação de usuário com controle de acesso rígido a todos os recursos.

Use o recurso de política de acesso de API para controlar o método de autenticação das APIs. Para obter mais informações, consulte API access policy.

Controles de acesso de Scripted REST API

As listas de controle de acesso (ACLs) definem critérios, como as funções necessárias e as condições que um usuário deve atender para acessar um endpoint ou REST API de script. Um usuário solicitante deve satisfazer pelo menos uma das ACLs. Não é necessário atender a todas as ACLs selecionadas. Você pode definir uma única ACL para uma REST API inteira ou para um endpoint individual.

Nota:

Por padrão, as REST APIs com script contêm uma ACL que proíbe usuários com a função snc_external de fazer solicitações à API.

Ao definir uma ACL de REST API com script, ela deve ter o valor de TipoREST_Endpoint.

Para obter informações adicionais sobre ACLs, consulte Regras da lista de controle de acesso e Configurar um recurso de REST API com script para exigir uma ACL.

Matriz de segurança de Scripted REST API

Existem 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.

Tabela 1. Segurança da REST API com script

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	Qualquer valor	Qualquer valor
O recurso requer somente autenticação básica. Nenhuma ACL é necessária.	Qualquer valor	Verdadeiro	Falso	Qualquer valor
O recurso requer somente autenticação básica. A ACL é obrigatória.	Nenhuma ACL selecionada	Verdadeiro	Verdadeiro	Nenhuma ACL selecionada
Uma ACL selecionada no registro do recurso é necessária.	Qualquer valor	Verdadeiro	Verdadeiro	Uma ou mais ACLs selecionadas
É necessária uma ACL selecionada no registro de API REST de script.	Uma ou mais ACLs selecionadas	Verdadeiro	Verdadeiro	Nenhuma ACL selecionada

Objetos de erro de Scripted REST API

As Scripted REST APIs 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 API REST de 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 Aceitar da solicitação. Se o cabeçalho Aceitar especificar um formato incompatível, como imagem/jpeg, a resposta de erro usará JSON.

As respostas de erro seguem este formato:

{
  "error": {
    "message": "My error message",
    "detail": "My details"  
  },  
  "status": "failure"
}

O código de status numérico, como 404, está incluído no cabeçalho do código de status da resposta, não no corpo da resposta.

Suporte ao Automated Test Framework

O Automated Test Framework (ATF) é compatível com etapas de teste de 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 das configurações da etapa de teste REST e Configurações da etapa de teste ATF REST.

Desenvolver treinamento

Em ServiceNow® Site do desenvolvedor, você pode encontrar treinamento para Scripted REST APIs.

• Criar uma REST API com script
  Crie uma REST API com script para definir endpoints de serviço web.
• Práticas recomendadas de Scripted REST APIs
  Siga estas diretrizes ao projetar e implementar REST APIs com script.
• Exemplos de Scripted REST API
  Vários exemplos estão disponíveis demonstrando como criar e usar REST APIs com script.