uMov.me API - Do básico ao avançado

Tutorial apresentando como funciona e exemplificando o uso da API do uMov.me para desenvolvedores.

1. UMOV.ME API
Do básico ao avançado
@nbluis
http://about.me/nbluis
Thursday, October 17, 13

2. 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
Thursday, October 17, 13

3. 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
Thursday, October 17, 13

4. COMO FUNCIONA ?
•Através de requisições HTTP
•Trafega informação por XML
•Utiliza conceitos de REST
Thursday, October 17, 13

5. COMO FUNCIONA ?
•Através de requisições HTTP
•Trafega informação por XML
•Utiliza conceitos de REST
Thursday, October 17, 13

6. ENTENDENDO HTTP
HTTP é o protocolo padrão utilizado na internet
É através de HTTP que nosso navegador acessa
qualquer site na internet
Thursday, October 17, 13

7. ENTENDENDO HTTP
Cliente Servidor
Requisição / Request
Resposta / Response
http://api.umov.me
Conteúdo da resposta
Thursday, October 17, 13

8. 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)
Thursday, October 17, 13

9. 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)
Thursday, October 17, 13

10. 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.
Thursday, October 17, 13

11. 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
Thursday, October 17, 13

12. COMO FUNCIONA ?
•Através de requisições HTTP
•Trafega informação por XML
•Utiliza conceitos de REST
Thursday, October 17, 13

13. ENTENDENDO XML
•É uma linguagem de marcação
•Baseado em tags
•Facil de representar estruturas complexas utilizando
texto
•Todo mundo conhece
Thursday, October 17, 13

14. EXEMPLO DE XML
<carro>
<marca>Fiat</marca>
<modelo>Uno</modelo>
<ano>2013</ano>
<portas>2</portas>
<utilitarios>
<utilitario nome=”Vidro Elétrico”/>
</utilitarios>
</carro>
Thursday, October 17, 13

15. COMO FUNCIONA ?
•Através de requisições HTTP
•Trafega informação por XML
•Utiliza conceitos de REST
Thursday, October 17, 13

16. ENTENDENDO REST
Um serviço REST nada mais é que utilizar o que já
aprendemos sobre HTTP para manusear este serviço.
Thursday, October 17, 13

17. EXEMPLO REST
Listar usuários: Incluir usuário:
Alterar usuário:Visualizar usuário:
GET: http://servico.com/user
Resposta:
<usuarios>
<usuario>123</usuario>
</usuarios>
GET: http://servico.com/user/123
Resposta:
<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>
Thursday, October 17, 13

18. 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
Thursday, October 17, 13

19. CRIANDO UM TOKEN
Para criar um TOKEN para um ambiente basta acessar a
tela de “Criação > Parâmetros” no uMov.Center
Thursday, October 17, 13

20. EXEMPLO DE ACESSO A API
GET:http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Thursday, October 17, 13

21. EXEMPLO DE ACESSO A API
GET:http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Método HTTP
Thursday, October 17, 13

22. EXEMPLO DE ACESSO A API
http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
URL Base
GET:
Thursday, October 17, 13

23. EXEMPLO DE ACESSO A API
http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Token de acesso
GET:
Thursday, October 17, 13

24. EXEMPLO DE ACESSO A API
http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Recurso acessado
GET:
Thursday, October 17, 13

25. EXEMPLO DE ACESSO A API
http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Formato
(apenas xml)
GET:
Thursday, October 17, 13

26. 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.
Thursday, October 17, 13

27. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Listar agentes:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Visualizar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Incluir um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Alterar um agente:
Exemplo utilizando agente como recurso
Thursday, October 17, 13

28. EXEMPLO DE ACESSO A API
Fique atento aos pontos destacados em cada operação
Thursday, October 17, 13

29. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Listar agentes:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Visualizar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Incluir um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Alterar um agente:
Thursday, October 17, 13

30. 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.xml
Visualizar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Alterar um agente:
Thursday, October 17, 13

31. EXEMPLO DE ACESSO A API
Para a maioria das demais operações basta alterar o
recurso na URL
Thursday, October 17, 13

32. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml
Listar itens:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml
Visualizar um item:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml
Incluir um item:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml
Alterar um item:
Exemplo utilizando item como recurso
Thursday, October 17, 13

33. 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.
Thursday, October 17, 13

34. EXEMPLO DE PESQUISA
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Listar 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 pesquisado
Quantidade de registros retornados
Identificador interno de cada registro
Link para acesso a visualização de cada registro
Thursday, October 17, 13

35. 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
Thursday, October 17, 13

36. 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
Thursday, October 17, 13

37. 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
Thursday, October 17, 13

38. EXEMPLO DE VISUALIZAÇÃO
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Visualizar 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
Thursday, October 17, 13

39. EXEMPLO DE INCLUSÃO
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Incluir 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>[email protected]</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 incluso
Link para acesso ao novo agente
Identificador do novo agente
Nome do recurso operado
Thursday, October 17, 13

40. EXEMPLO DE ALTERAÇÃO
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Alterar 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
Thursday, October 17, 13

41. 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
Thursday, October 17, 13

42. EXEMPLO IDENTIFICADOR
ALTERNATIVO
GET: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml
Visualizar um agente:
POST: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml
Alterar um agente:
O início da URL (http://api.umov.me/CenterWeb) foi omitida nos exemplos abaixo
Thursday, October 17, 13

43. VISUALIZANDO ERROS
Sempre que ocorrer o erro em decorrência de uma
requisição, a mensagem será retornada permitindo um
melhor entendimento do problema
Thursday, October 17, 13

44. EXEMPLO DE ERRO
Retorno:
<result>
<statusCode>400</statusCode>
<errors>login: error.mandatory.field</errors>
<resourceName>agent</resourceName>
</result>
Código de erro http retornado
Campo e mensagem de erro
Recurso manipulado pela requisição
Thursday, October 17, 13

45. OBRIGADO
@nbluis
http://about.me/nbluis
Thursday, October 17, 13