Serviços Web de Entrada REST

Este tópico fornece mais informações sobre o suporte do produto a serviços REST usando IWS.

O mecanismo REST verifica o cabeçalho Aceitar-Idioma e tenta localizar um idioma suportado cuja localidade corresponde ao idioma referenciado. Se encontrada, a resposta do serviço Web retorna quaisquer dados traduzíveis nesse idioma. Observe que, se nenhum idioma suportado for encontrado para os idiomas fornecidos no cabeçalho Aceitar-Idioma, o sistema usará o idioma do usuário que enviou a solicitação.

Os registros REST IWS são marcados com uma versão do mecanismo REST de 1.0 ou 2.0. Versão 2.0 é a versão usada para novos serviços. A versão 1.0 foi introduzida para compatibilidade retroativa. Alguns dos comportamentos do sistema são diferentes com base na versão do serviço REST. As seções abaixo destacam os casos em que isso ocorre.

Método e Parâmetros HTTP

Ao definir operações para serviços Web de entrada REST, o produto é compatível com os métodos HTTP Get, Patch, Post, Put e Delete. Observe que o suporte do produto a esses métodos HTTP é um meio de comunicar o propósito do serviço Web ao mundo exterior. Entretanto, o comportamento real do serviço Web REST é dirigido pelo comportamento do objeto baseado pelo esquema subjacente (objeto de negócios, serviço de negócios ou script de serviço). Por exemplo, é possível configurar o Método HTTP "Put" para uma operação que faça referência a um script de serviço que apenas recupera um registro. O produto não é capaz de detectar esse tipo de discrepância. Usuários da configuração devem considerar com cuidado o método correto a ser usado com base na lógica desse serviço.

Para operações que fazem referência a um objeto de negócios, o tipo de transação deve ser fornecido. A sintaxe REST não é compatível com a definição do tipo de transação no tempo de execução. Há algumas verificações de validação básicas nesse caso, relacionadas ao tipo de transação e ao método HTTP. Por exemplo, um método Get só faz sentido com o tipo de transação Read.

Observação: O uso do tipo de transação Alterar exige que todos os valores sejam transmitidos. O uso do tipo de transação Atualizar permite que o serviço Web transmita apenas a chave primária e os valores a serem atualizados. Todos os outros elementos manterão os valores existentes.

Você também pode definir parâmetros. Para cada parâmetro, você define uma referência externa ao elemento, que é como esse parâmetro é exposto aos autores de chamada externos e é definido na especificação da API. Cada um desses parâmetros é mapeado ao XPath do elemento do esquema a partir do objeto de negócios subjacente, do serviço de negócios ou do script de serviço. Para cada parâmetro, você indica se é um parâmetro Path ou um parâmetro Query.

Parâmetros Path são parâmetros que são uma parte do endpoint e são obrigatórios. Cada parâmetro precisa ser incluído no componente de URI da operação envolvido por chaves (ou seja: "{...}").
Parâmetros Query são opcionais. Eles não fazem parte do endpoint; em vez disso, são incluídos no URL do endpoint depois de um ponto de interrogação, seguido pelos pares de valor do nome.

Consulte a seção URL abaixo para ver exemplos de parâmetros path e query nos URLs de amostra.

Composição do URL

Ao criar o URL do endpoint para um serviço REST, há três partes principais que juntas formam o URL completo.

A primeira parte é específica do componente. Ela será diferente em uma implementação no local, se comparada a uma implementação na nuvem. As duas terão o host e o port e, em seguida, componentes adicionais que identificam o ambiente.
A segunda parte é este caminho inserido no código designado pelo produto: "/rest/apis".

Essas duas partes do URL são definidas na variável de substituição F1_REST_BASE_URL. Isso é definido ao inicializar o ambiente. Consulte o Server Administration Guide para obter mais informações.

A parte restante do URL é criada dinamicamente com base na configuração de cada Serviço Web de Entrada e nas operações dele. Os componentes são "/ownerURIComponent/resourceCategoryURIComponent/iwsURIComponent/operationURIComponent"

O componente do URI do proprietário é retirado da flag de proprietário do serviço Web de entrada REST. Uma consulta extensível externa (Configuração do Proprietário para Serviços REST) define esse componente para cada flag de proprietário.
Cada Serviço Web de Entrada REST precisa fazer referência a uma categoria de recurso. Essa categoria é utilizada para associar serviços Web relacionados a categorias comuns de recursos. Para múltiplos registros do Serviço Web de Entrada vinculados à mesma categoria de recurso, catálogos externos podem usar essas informações para agrupar serviços Web relacionados. A categoria do recurso é uma consulta extensível, e o componente do URI é um atributo desse registro.
Cada registro do Serviço Web de Entrada REST define um componente de URI que serve como um identificador externo desse registro do Serviço Web de Entrada. O valor precisa ser exclusivo dentro de uma determinada flag de proprietário.
Cada operação precisa definir o Método HTTP e, opcionalmente, um componente de URI. Ao definir parâmetros de caminho, os parâmetros de caminho devem ser incluídos no componente de URI usando chaves.

Em todos os casos, o componente de URI precisa começar com um traço ('/').

A seguir, veja alguns exemplos da porção dinâmica do URL de um serviço REST. O último exemplo mostra o uso de um parâmetro query.


Nome do IWS Componente URI	Proprietário Componente URI	Categoria de Recurso Componente URI	Método HTTP da Operação Componente URI	Componente do URL Dinâmico	Exemplo do Tempo de Execução
c1rateCalculation /rateCalculation	C1 /customer	C1-RATES /rates	Post /	../customer/rates/rateCalculation/	../customer/rates/rateCalculation/
w1WorkActivity /workActivity	W1 /asset	W1-WORK /work	Get /{activityId}	../asset/work/workActivity/{activityId}	../asset/work/workActivity/5798165498
w1WorkActivity /workActivity	W1 /asset	W1-WORK /work	Patch /scheduleWindow/{externalSystem}/{activityId}/{windowStartDateTime}	../asset/work/workActivity/scheduleWindow/{externalSystem}/{activityId}/{windowStartDateTime}	../asset/work/workActivity/scheduleWindow/MY-COMPANY/5798165498/20190101
CM-AccountActivityHistory /accountActivityHistory	CM /cm	CM-ACCT-INFO /accountInformation	Get /{accountId}	../cm/accountInformation/accountActivityHistory/{accountId}	../cm/accountInformation/accountActivityHistory/123456789?activityId=5468976

Formato de Carga Útil

Os serviços REST suportam o recebimento de uma carga útil de solicitação no formato XML ou JSON e retorna a carga útil em XML ou JSON. O formato padrão retornado depende do valor da Versão do Mecanismo REST.

Os serviços da versão 2.0 pressupõem que o formato JSON seja o padrão. O padrão pode ser substituído fornecendo um cabeçalho de aceitação de aplicativo/XML.
Os serviços da versão 1.0 pressupõem que o formato XML seja o padrão. O padrão pode ser substituído fornecendo um cabeçalho de aceitação de aplicativo/JSON.

Nó Raiz para Formato JSON

Os serviços da Versão 2.0 com a carga útil formatada em JSON não aceitam na solicitação ou retornam na resposta em qualquer nó raiz ao redor da carga útil. Veja a seguir um exemplo da resposta de uma chamada REST para um serviço da versão 2.0:

{
   "batchJobId": "string",
   "requestSuccessful": "string"
}

Os serviços da versão 1.0 com a carga útil formatada em JSON esperam um nó raiz na solicitação e retornam um na resposta. Veja a seguir um exemplo da resposta de uma chamada REST para um serviço da versão 1.0:

{
  "F1CnclBatJob": {
    "batchJobId": "string",
    "requestSuccessful": "string"
 }
}

A Especificação da API Aberta visível na página de manutenção do serviço Web de entrada exibe o formato esperado com base na versão do mecanismo REST do registro ao exibir a especificação.

Formato de Tipo de Dados no JSON

No formato JSON, as strings são cercadas por aspas e números e os dados boolianos não têm aspas. Todos os serviços do mecanismo REST versão 2.0 seguem este padrão. Originalmente, os serviços que são o mecanismo REST versão 1.0 estavam tratando incorretamente números e dados boolianos como strings e retornando os dados com aspas. Essa informação foi corrigida.

Para acomodar qualquer integração que possa ter trabalhado no comportamento dos serviços da versão 1.0, o sistema permite identificar serviços Web de entrada que são exceções a essa regra. Para qualquer serviço Web de entrada identificado como uma exceção, o sistema continua tratando números e dados boolianos como strings em respostas JSON. Para adicionar um ou mais registros IWS à lista de exceções:

Ir para Configuração do Recurso.
Procure uma configuração de recurso existente com o tipo de recurso Mensagens Externas. Se não houver uma, crie uma.
Adicione uma opção para o tipo de opção Exceções de Tipo de Dados JSON do IWS.
No valor de opção, indique o registro IWS que é uma exceção. Observe que várias opções para o tipo de opção podem ser adicionadas. Além disso, o valor de opção suporta uma lista delimitada por vírgulas.

Esquema Externo

Por padrão, o esquema do serviço subjacente (por exemplo, script de serviço, objeto de negócios ou serviço de negócios) também é o esquema da operação do serviço Web de entrada REST e atua como o esquema Solicitação e Resposta. O produto permite definir um esquema explícito para uma operação de serviço Web de entrada (IWS) REST, permitindo que um usuário ajuste o esquema para um consumidor externo. O esquema de operação IWS também suporta algumas configurações especiais que permitem que recursos adicionais sejam definidos apenas para o esquema de operação IWS.

O esquema de operação suporta os seguintes recursos:

Declarar se um elemento pertence apenas ao esquema de solicitação, somente ao esquema de resposta, ambos (padrão) ou excluídos por completo. Isso é usado para estabelecer uma separação clara entre as definições de esquema de solicitação e resposta.
Atribuir um nome de elemento diferente a um elemento interno. Isso permite que o nome do elemento de serviço interno se alinhe mais de perto às referências internas ao elemento, se necessário. O nome do elemento de face externa pode ser diferente, permitindo um esquema mais legível.
Apresente elementos especializados que ofereçam suporte a vínculos e outros tipos de padrões estruturais de forma que não afetem o processamento de serviços internos.

Consulte Nós e Atributos do Esquema do Web Service para obter mais informações.

O servlet REST usa os esquemas de solicitação e resposta para mapear elementos para e do esquema interno.

Observação: Embora o chamador deva fornecer apenas elementos definidos pelo esquema de solicitação, o aplicativo não filtra elementos estranhos. Pressuposto que o serviço interno foi projetado para ignorar esses elementos. No entanto, apenas os elementos definidos pelo esquema de resposta são incluídos na resposta.

Links Dinâmicos

Há casos de uso em que a API publicada inclui um elemento "_ self" que contém o URL de ponto final da operação GET relacionada aos dados retornados na resposta. Além disso, as cargas úteis de resposta podem incluir chaves externas e para essas entidades, a resposta inclui um elemento "_ link" que contém o URL de ponto final da operação GET para essa entidade (se ela existir).

A sintaxe é fornecida no esquema de operação de serviço Web de entrada REST para suportar a criação do URL de ponto final de runtime para os elementos de link _ self e _. Além de construir dinamicamente a parte estática do URL com base nos detalhes do ambiente atual, ele também cria a parte dinâmica do URL, substituindo os componentes do URL para a operação e substituindo os parâmetros do caminho. A sintaxe permite que você defina uma Operação IWS específica ou permite que você faça referência a um objeto de manutenção e, no tempo de execução, o sistema determina a operação GET para o objeto de manutenção e cria o URL adequadamente.

Exemplo da sintaxe:


  <_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

Exemplo do URL do ponto final de runtime:


  _link: "http://.../common/toDos/toDoEntries/28937296450934"

Uma operação GET pode ser associada a um objeto de manutenção para indicar que essa é a operação GET padrão da entidade. Uma opção Operação GET no nível do Objeto de Manutenção e do Objeto de Negócios pode ser usada para substituir esse padrão. Se a entidade não estiver associada a um objeto de negócios ou o último não estiver associado a essa opção, a operação associada ao objeto de manutenção (se houver) será usada.

Abrir Documentação de Especificação da API

As seguintes informações de documentação podem ser fornecidas para um Serviço Web de Entrada:

Descrição curta e detalhada de cada operação.
O texto de ajuda pode ser fornecido para elementos individuais. O mesmo texto pode ser compartilhado entre vários elementos em todas as operações do Serviço Web de Entrada. Se um elemento não estiver associado ao texto de ajuda, o rótulo do campo interno será usado.
A solicitação de amostra e os documentos de resposta podem ser fornecidos para cada operação.
As operações podem ser associadas a um número de sequência que controla a ordem em que elas aparecem na Especificação de API Aberta.

Observação: As descrições detalhadas e o texto de ajuda relacionado ao elemento não são traduzidos, pois o catálogo publicado para APIs do produto base está apenas no idioma inglês.