Scripted REST APIs

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

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

Figura 1. Formulário de Serviço REST de 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 APIs

Os URIs de Scripted REST APIs 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 da Web no escopo global, o namespace é o valor da propriedade glide.appcreator.company.code. Para serviços da 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ões especificando o URI sem um número de versão.
• <api_id>: valor do campo ID da API no formulário Serviço REST de 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 de 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 de mensagem .

Controle de versões de Scripted REST API

Os URIs de Scripted REST APIs 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 de 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 de 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 quaisquer 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 request.

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 com 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 de Scripted REST APIs

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

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 REST API ou endpoint 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 de script contêm uma ACL que proíbe os 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 API REST de 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 de 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 de Scripted REST APIs

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. ACL é necessária.	Nenhuma ACL selecionada	Verdadeiro	Verdadeiro	Nenhuma ACL selecionada
Uma ACL selecionada no registro do recurso é obrigatória.	Qualquer valor	Verdadeiro	Verdadeiro	Uma ou mais ACLs selecionadas
Uma ACL selecionada no registro da REST API com script é obrigatória.	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 REST API com script para alertar os clientes solicitantes sobre erros. Use objetos de erro para responder às solicitações recebidas, 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 sem suporte, 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 ATF ( Automated Test Framework ) 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 das configurações da etapa de teste REST e Configurações da etapa de teste ATF REST.

Desenvolver treinamento

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

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