Modelagem

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.

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.

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:

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.

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ódigos de Erro do Cliente

Códigos de Erro 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'"
	]
}