Padrões e tecnologias

A API de integração com o marketplace do Grupo Netshoes utiliza os conceitos de arquitetura Restful. Sendo que, para isso os seguintes padrões e tecnologias são empregados na solução.

REST

Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP.

Mais informações.

HTTP 1.1

Padrão para descrição de dados utilizado para intercâmbio de informações entre sistemas, é mais simples e leve do que algumas alternativas de mercado, como XML.

Mais informações.

JSON

Protocolo de transporte padrão, amplamente utilizado.

Mais informações.

UTF-8

Conjunto de caracteres padrão para comunicação entre sistemas distribuídos.

Mais informações.

ISO-8601

Padrão de formato específico para dados do tipo data e hora.

"Padrão": "YYYY-MM-DDThh:mm:ss.sTZD"
"Exemplo": "2015-10-28T09:25:00.000-03:00"

Mais informações.

Recursos e Operações

Os recursos definidos na API do marketplace seguem o padrão Restful e, utilizam as operações padrões do protocolo HTTP para processamento das chamadas.

A tabela abaixo define a ação esperada para cada um dos métodos utilizados pela API.

Método HTTP Ações
GET

Consulta de um ou mais recursos do marketplace.

Essa operação permite que um ou mais recursos seja pesquisado de acordo com os filtros informados na URI do recurso. Saiba mais no tópico Buscas e Paginação, ou veja as operações de consulta disponíveis no API Browser.

POST

Cria um novo recurso.

Essa operação recebe a estrutura JSON do recurso que deverá ser criado e retorna ao consumidor a mesma estrutura já processada pelo marketplace. Assim o consumidor pode utilizar a estrutura de links (veja mais em HATEOAS) disponibilizada, para poder realizar outras operações no recurso criado.

PUT

Atualiza um recurso existente.

Essa operação recebe a estrutura JSON do recurso que deverá ser alterado e retorna a mesma estrutura já processada pelo marketplace, juntamente com os links relacionados ao recurso.

Buscas e Paginação

Existem duas formas de realizar a busca de dados na API do marketplace.

Busca de Coleções

A busca por coleções deverá ser utilizada em conjunto com os parâmetros de paginação. Em geral todos os serviços que retornam grande quantidade de dados sempre utilizam paginação para devolver os registros.

GET http://api-sandbox.netshoes.com.br/api/v2/products?page=0&size=20

Busca Específica

A busca de um recurso específico deverá ser realizada quando o lojista já tiver o conhecimento da existência do recurso que deve ser pesquisado.

A idetificação do recurso deverá ser informada na composição da URI de consulta, como no exemplo abaixo:

GET http://api-sandbox.netshoes.com.br/api/v2/products/12479

Parâmetro Expand

Sempre que houver a necessidade do retorno de maiores detalhes sobre algum dos atributos do recurso desejado, o parâmetro expand poderá ser utilizado.

Recomenda-se a utilização do size no máximo 50 (size=50) caso contrário, poderá ocorrer time-out ao utilizar o método GET.

GET http://api-sandbox.netshoes.com.br/api/v2/products?page=0&size=20&expand=attributes

GET http://api-sandbox.netshoes.com.br/api/v2/products/12479?expand=attributes

Hypermedia (HATEOAS)

HATEOAS (Hypermedia as the Engine of Application State) possibilita que as aplicações consumidoras possam interagir com a API do marketplace basicamente através de informações de hypermedia retornadas em cada recurso.

Em arquiteturas orientadas a serviços (SOA), as regras de comunicação entre cliente e servidor são estabelecidas através de uma interface definida entre as partes, normalmente WSDL. A utilização de HATEOAS permite que a disponibilização de novas interações ocorra de forma dinâmica e que as aplicações consumidoras tomem conhecimento das novas opções de interação sem que sejam impactadas.

Estrutura de Hypermedia

Todos os recursos da API deverão conter a seguinte estrutura de links, indicando as possibilidades de interação com o recurso em questão:

"links":[
	{
		"rel":"self",
		"href":"https://api-sandbox.netshoes.com.br/api/v2/products/?page=0&size=20"
	},
	{
		"rel":"first",
		"href":"https://api-sandbox.netshoes.com.br/api/v2/products/?page=0&size=20"
	},
	{
		"rel":"last",
		"href":"https://api-sandbox.netshoes.com.br/api/v2/products/?page=0&size=20"
	}
]

Códigos de Sucesso

A API retornará os códigos HTTP Status para cada request.

Código HTTP

Descrição

Métodos HTTP

200

Indica que o processamento foi realizado corretamente e o retorno será conforme a expectativa.

GET

201

Indica que o recurso foi criado com sucesso. Deverá retornar o header Location: indicando a URI do novo recurso.

POST

202

Indica que o processamento será assíncrono, portanto, além do header Location, deverá retornar o conteúdo com um atributo status.

POST PUT

204

Indica que a solicitação foi processada, mas a busca nenhum registro pode ser encontrado.

GET

206

Indica que os dados foram processados parcialmente e os problemas dos itens não processados serão informados na resposta do servidor.

POST

Códigos de Erro do Cliente

Código HTTP

Descrição

400

Requisição mal formada.

401

Requisição requer autenticação. Acontece quando não é enviado o TOKEN na requisição, ou quando ele está inválido.

403

Requisição negada.

404

Recurso não encontrado.

405

Método não permitido.

406

Conteúdo ou Content-type inválido.

408

Tempo esgotado para a requisição.

409

Recurso já cadastrado.

413

Requisição excede o tamanho máximo permitido.

415

Tipo de mídia inválida (falta de informar o Content-Type correto).

422

Exceções de negócio.

429

Requisição excede a quantidade máxima de chamadas permitidas à API.

Códigos de Erro do Servidor

Código HTTP

Descrição

5xx

Erro interno inesperado do servidor.

Estrutura de Erro

Em caso de erros, a resposta ao recurso deverá retornar uma estrutura específica, como definido abaixo:

{
    "type":"Bad_Request_Error",
    "description":"Request invalid or malformed.",
    "notifications":[
		"Error on save sku:111-0457-178-52 Produto com código '111-0457-178-52' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-17'",
		"Error on save sku:111-0457-178-85 Produto com código '111-0457-178-85' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-07'",
		"Error on save sku:111-0457-178-23 Produto com código '111-0457-178-23' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-06'"
	]
}