Especificações das trocas REST

Os Web Services usam os princípios comuns das API REST. O formato para as trocas é o JSON.

Autenticação

A API REST usa a autenticação básica. Para maiores informações, consultar: Fase de autenticação. Para encontrar suas chaves, consulte o artigo seguinte: Requisitos.

Parâmetros da solicitação

A aplicação espera um JSON válido como entrada de solicitação. Por exemplo, Charge/SDKTest tomará Type/String object como valor de entrada.

A chamada deve ser realizada como segue:

/pt-BR/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/SDKTest.php#L16-L26

https://api.lyra.com/api-payment/V4/Charge/SDKTest

{
    "value": "my testing value"
}

/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);

Parâmetros da resposta

Quando o Web Service responde, ele retorna:

{
    "webService":"Charge/SDKTest",
    "version":"V4",
    "applicationVersion":"4.1.2",
    "status":"SUCCESS",
    "answer": {
        "value":"my testing value",
        "_type":"V4/Type/String"
    },
    "ticket":null,
    "serverDate":"2018-10-02T16:13:57+00:00",
    "applicationProvider":"LYRA",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

O objeto solicitado é retornado em um objeto de resposta genérico que:

PARÂMETROS	type	Descrição
webService	String	web service chamado, formato: [namespace]/[web_service_name]
version	String	versão da API
status	String	status da resposta: SUCCESS ou ERROR
answer	Objeto	resposta profissão
ticket	String	número de ticket para enviar ao suporte (não implementado)
applicationProvider	String	plataforma que realiza o serviço
applicationVersion	String	versão da aplicação
metadata	Objeto	restrito ao uso interno
serverDateTime	String	data do servidor que respondeu, em UTC
_type	String	tipo do objeto. Começa sempre pelo número de versão

Gerenciamento dos erros

No caso de erro do Web Service:

/pt-BR/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
    "amount": -1
}

A resposta é:

{
	"webService": "Charge/CreatePayment",
	"version": "V4",
	"applicationVersion": "4.5.1",
	"status": "ERROR",
	"answer": {
		"errorCode": "INT_902",
		"errorMessage": "web-service input data validation error",
		"detailedErrorCode": null,
		"detailedErrorMessage": "can't decode JSON data : {\n    \"amount\":   -1,\n}",
		"ticket": "null",
		"_type": "V4/WebService/WebServiceError"
	},
	"ticket": null,
	"serverDate": "2018-12-10T19:27:32+00:00",
	"applicationProvider": "",
	"metadata": null,
	"_type": "V4/WebService/Response"
}

O Web Service falhou e retorna um objeto WebService/WebServiceError:

Parâmetro	type	Descrição
errorCode	String	Código de erro (no formato [PREFIXO]_[CÓDIGO])
errorMessage	String	Mensagem de erro
detailedErrorCode	String	Código de erro detalhado (ou null)
detailedErrorMessage	String	Mensagem detalhada (ou null)

Para maiores detalhes sobre os erros, consultar: Códigos de erro.

Por que a API não é totalmente RESTful?

Decidimos desenvolver uma API da forma mais simples que puder para evitar erros comuns:

Usamos somente o método POST.

Podemos assim evitar questões clássicas como qual método usar. É SEMPRE O POST.

Todos os parâmetros de solicitação são enviados sob a forma de um objeto JSON :

Só tem uma maneira de enviar parâmetros (sem acrescentar nada ao URI).
Os jornais ficam mais simples.
A API responde sempre HTTP 200

Não é portanto necessário gerar diversos códigos de status HTTP, a resposta é sempre 200. O status do Web Service pode ser consultado dentro do objeto JSON.

Data e hora

O objeto datetime está no formato ISO 8601.

O Web Service aceita todos os fusos horários tais como:

2015-11-19T16:56:57+00:00
2015-11-19T16:56:57+01:00
2015-11-19T16:56:57+Z

O servidor sempre retorna o objeto datetime no fuso horário UTC (GMT+00):

2015-11-19T16:56:57+00:00

O servidor nunca retorna 2015-11-19T16:56:57+Z

Valores nulos

Os valores nulos não obrigatórios são automaticamente ausentes da resposta. Ou seja, uma propriedade nula se encontra na resposta somente si a chave se tornou obrigatória, e se null for um valor aceitável.

Categoria

Tags