UMOV.ME APIDo básico ao avançado

@nbluishttp://about.me/nbluis

O QUE É ?

• Maneira fácil (para desenvolvedores) de realizar integração online com uMov.me

• Permite pesquisar, visualizar e manter praticamente todos os cadastros do sistema

• Permite ainda realizar algumas operações avançadas dentro do sistema

O QUE NÃO É ?

• Uma forma diferente de usuários operarem o sistema

• Um serviço a ser consumido por usuários finais (Agentes, Vendedores, etc.)

• Solução ideal para qualquer tipo de integração com uMov.me

COMO FUNCIONA ?

• Através de requisições HTTP

• Trafega informação por XML

• Utiliza conceitos de REST

COMO FUNCIONA ?

• Através de requisições HTTP

• Trafega informação por XML

• Utiliza conceitos de REST

ENTENDENDO HTTP

HTTP é o protocolo padrão utilizado na internet

É através de HTTP que nosso navegador acessa qualquer site na internet

ENTENDENDO HTTP

Cliente ServidorRequisição / Request

Resposta / Response

http://api.umov.me

Conteúdo da resposta

ENTENDENDO HTTP

A requisição é composta por 4 informações básicas

Método (Method)

Endereço (URL)

Conteúdo (Content/Payload)

Cabeçalhos adicionais (Headers)

ENTENDENDO HTTP

A resposta é composta por 4 informações básicas

Status code (Código de status de sucesso ou erro)

Resposta

Cabeçalhos adicionais (Headers)

PRINCIPAIS MÉTODOS HTTP

• GET - Busca uma informação do servidor

• POST - Atualiza uma informação no servidor

• Existem outros (PUT / HEAD / DELETE) mas não são utilizados por nossa api.

EXEMPLO DE REQUISIÇÃO

• Método: GET

• URL: http://google.com

• Conteúdo: NENHUM

• Cabeçalhos: NENHUM

• Método: POST

• URL: http://google.com/createUser

• Conteúdo: userName=Eduardo&password=senha

• Cabeçalhos: NENHUM

COMO FUNCIONA ?

• Através de requisições HTTP

• Trafega informação por XML

• Utiliza conceitos de REST

ENTENDENDO XML

• É uma linguagem de marcação

• Baseado em tags

• Facil de representar estruturas complexas utilizando texto

• Todo mundo conhece

EXEMPLO DE XML<carro> <marca>Fiat</marca> <modelo>Uno</modelo> <ano>2013</ano> <portas>2</portas> <utilitarios> <utilitario nome=”Vidro Elétrico”/> </utilitarios></carro>

COMO FUNCIONA ?

• Através de requisições HTTP

• Trafega informação por XML

• Utiliza conceitos de REST

ENTENDENDO REST

Um serviço REST nada mais é que utilizar o que já aprendemos sobre HTTP para manusear este serviço.

EXEMPLO REST

Listar usuários: Incluir usuário:

Alterar usuário:Visualizar usuário:

GET: http://servico.com/userResposta: <usuarios> <usuario>123</usuario> </usuarios>

GET: http://servico.com/user/123Resposta: <usuario> <id>123</id> <nome>Eduardo</nome> </usuarios>

POST: http://servico.com/user<usuario> <nome>Novo usuário</nome></usuarios>

POST: http://servico.com/user/123<usuario> <nome>Novo nome</nome></usuarios>

ENTRANDO NO UMOV.ME

Agora que entendemos um mínimo sobre APIs vamos ao uMov.me

No uMov.me é necessário utilizar um TOKEN de acesso para realizar a autenticação na API

CRIANDO UM TOKEN

Para criar um TOKEN para um ambiente basta acessar a tela de “Criação > Parâmetros” no uMov.Center

EXEMPLO DE ACESSO A APIGET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

EXEMPLO DE ACESSO A APIGET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

Método HTTP

EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

URL Base

GET:

EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

Token de acesso

GET:

EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

Recurso acessado

GET:

EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

Formato (apenas xml)

GET:

EXEMPLO DE ACESSO A API

Todos os recursos disponíveis da API uMov.me está disponível na KB: http://kb.umov.me/?q=pt-br/node/914

A maioria das operações da API segue um modelo muito parecido de cadastro que será mostrado a seguir.

EXEMPLO DE ACESSO A API

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlListar agentes:

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlVisualizar um agente:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlIncluir um agente:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlAlterar um agente:

Exemplo utilizando agente como recurso

EXEMPLO DE ACESSO A API

Fique atento aos pontos destacados em cada operação

EXEMPLO DE ACESSO A API

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlListar agentes:

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlVisualizar um agente:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlIncluir um agente:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlAlterar um agente:

EXEMPLO DE ACESSO A API

Para visualizar ou alterar um agente específico precisamos informar qual agente queremos, utilizando

o seu id.

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlVisualizar um agente:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlAlterar um agente:

EXEMPLO DE ACESSO A API

Para a maioria das demais operações basta alterar o recurso na URL

EXEMPLO DE ACESSO A API

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xmlListar itens:

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xmlVisualizar um item:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xmlIncluir um item:

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xmlAlterar um item:

Exemplo utilizando item como recurso

EXEMPLOS ADICIONAIS

Os exemplos a seguir aprofundam um pouco mais cada operação da API.

A maioria dos demais recursos da API podem ser operados utilizando o mesmo formato ao que está

sendo mostrado.

EXEMPLO DE PESQUISA

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlListar agentes:

Resposta:<result> <resourceName>agent</resourceName> <size>2</size> <entries> <entry id="1" link="/agent/1.xml"/> <entry id="2" link="/agent/2.xml"/> </entries></result>

Nome do recurso pesquisadoQuantidade de registros retornados

Identificador interno de cada registro

Link para acesso a visualização de cada registro

APROFUDANDO A PESQUISA

A pesquisa permite também que filtremos informações por qualquer campo da entidade sendo pesquisada

através da URL

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml?active=true

Exemplo

APROFUDANDO A PESQUISA

Permite ainda pesquisas por campos de entidades relacionadas ao recurso

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml?agentType.description=Vendedores

Exemplo

LIMITE DA PESQUISA

Independente dos filtros informados, o retorno sempre está sujeito a limitação de registros retornados

Por padrão este limite é de 20 registros

EXEMPLO DE VISUALIZAÇÃO

GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlVisualizar um agente:

Resposta: <agent> <id>123</id> <name>Joao da Silva</name> <login>joaosilva</login> <agentType> <id>1234</id> <description>Vendedor</description> </agentType> <active>false</active> <alternativeIdentifier/> .... </agent>

XML apresentando todos os campos visíveis do recurso

EXEMPLO DE INCLUSÃO

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xmlIncluir um agente:

Envio: <agent> <active>true</active> <agentType><id>1234</id></agentType> <login>fulano</login> <name>Fulano da Silva</name> <password>minha_senha_nao_criptografada</password> <email>fulano@empresa.com</email> <centerwebUser>true</centerwebUser> <mobileUser>true</mobileUser> <centerwebUserRole>D</centerwebUserRole> </agent>

Resposta: <result> <resourceName>agent</resourceName> <resourceId>1234</resourceId> <link>/agent/1234.xml</link> </result>

Dados do agente a ser inclusoLink para acesso ao novo agente

Identificador do novo agente

Nome do recurso operado

EXEMPLO DE ALTERAÇÃO

POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xmlAlterar um agente:

Envio: <agent> <name>Novo Nome</name> </agent>

Resposta: <result> <resourceName>agent</resourceName> <resourceId>1234</resourceId> <link>/agent/1234.xml</link> </result>

Dados do agente a ser alterado (apenas os dados a serem modificados)

Link para acesso ao agente alterado

Identificador do agente alterado

Nome do recurso operado

UTILIZANDO IDENTIFICADOR

Todas as requisições básicas permitem operar os recursos da API também pelo identificador alternativo

Nesse caso os XMLs não mudam, mudam apenas a URL

EXEMPLO IDENTIFICADOR ALTERNATIVO

GET: /123exxxxxxxxx/agent/alternativeIdentifier/123.xmlVisualizar um agente:

POST: /123exxxxxxxxx/agent/alternativeIdentifier/123.xmlAlterar um agente:

O início da URL (http://api.umov.me/CenterWeb) foi omitida nos exemplos abaixo

VISUALIZANDO ERROS

Sempre que ocorrer o erro em decorrência de uma requisição, a mensagem será retornada permitindo um

melhor entendimento do problema

EXEMPLO DE ERRO

Retorno: <result> <statusCode>400</statusCode> <errors>login: error.mandatory.field</errors> <resourceName>agent</resourceName> </result>

Código de erro http retornadoCampo e mensagem de erro

Recurso manipulado pela requisição

OBRIGADO

@nbluishttp://about.me/nbluis