O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

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

2.445 visualizações

Publicada em

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

Publicada em: Tecnologia
  • Entre para ver os comentários

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

  1. 1. UMOV.ME API Do básico ao avançado @nbluis http://about.me/nbluis
  2. 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
  3. 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
  4. 4. COMO FUNCIONA ? • Através de requisições HTTP • Trafega informação por XML • Utiliza conceitos de REST
  5. 5. COMO FUNCIONA ? • Através de requisições HTTP • Trafega informação por XML • Utiliza conceitos de REST
  6. 6. ENTENDENDO HTTP HTTP é o protocolo padrão utilizado na internet É através de HTTP que nosso navegador acessa qualquer site na internet
  7. 7. ENTENDENDO HTTP Cliente Requisição / R equest http://api.umo v.me nse sposta / Respo Re sta eúdo da respo Cont Servidor
  8. 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)
  9. 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)
  10. 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.
  11. 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
  12. 12. COMO FUNCIONA ? • Através de requisições HTTP • Trafega informação por XML • Utiliza conceitos de REST
  13. 13. ENTENDENDO XML •É uma linguagem de marcação • Baseado • Facil em tags de representar estruturas complexas utilizando texto • Todo mundo conhece
  14. 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>
  15. 15. COMO FUNCIONA ? • Através de requisições HTTP • Trafega informação por XML • Utiliza conceitos de REST
  16. 16. ENTENDENDO REST Um serviço REST nada mais é que utilizar o que já aprendemos sobre HTTP para manusear este serviço.
  17. 17. EXEMPLO REST Listar usuários: Incluir usuário: GET: http://servico.com/user Resposta: <usuarios> <usuario>123</usuario> </usuarios> POST: http://servico.com/user <usuario> <nome>Novo usuário</nome> </usuarios> Visualizar usuário: Alterar usuário: GET: http://servico.com/user/123 Resposta: <usuario> <id>123</id> <nome>Eduardo</nome> </usuarios> POST: http://servico.com/user/123 <usuario> <nome>Novo nome</nome> </usuarios>
  18. 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
  19. 19. CRIANDO UM TOKEN Para criar um TOKEN para um ambiente basta acessar a tela de “Criação > Parâmetros” no uMov.Center
  20. 20. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
  21. 21. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Método HTTP
  22. 22. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml URL Base
  23. 23. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Token de acesso
  24. 24. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Recurso acessado
  25. 25. EXEMPLO DE ACESSO A API GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Formato (apenas xml)
  26. 26. EXEMPLO DE ACESSO A API A maioria das operações da API segue um modelo muito parecido de cadastro que será mostrado a seguir. Todos os recursos disponíveis da API uMov.me está disponível na KB: http://kb.umov.me/?q=pt-br/node/914
  27. 27. EXEMPLO DE ACESSO A API Exemplo utilizando agente como recurso Listar agentes: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Visualizar um agente: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml Incluir um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Alterar um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
  28. 28. EXEMPLO DE ACESSO A API Fique atento aos pontos destacados em cada operação
  29. 29. EXEMPLO DE ACESSO A API Listar agentes: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Visualizar um agente: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml Incluir um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml Alterar um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
  30. 30. EXEMPLO DE ACESSO A API Para visualizar ou alterar um agente específico precisamos informar qual agente queremos, utilizando o seu id. Visualizar um agente: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml Alterar um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
  31. 31. EXEMPLO DE ACESSO A API Para a maioria das demais operações basta alterar o recurso na URL
  32. 32. EXEMPLO DE ACESSO A API Exemplo utilizando item como recurso Listar itens: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml Visualizar um item: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml Incluir um item: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml Alterar um item: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml
  33. 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.
  34. 34. EXEMPLO DE PESQUISA Listar agentes: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml 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 Link para acesso a visualização de cada registro Identificador interno de cada registro
  35. 35. APROFUDANDO A PESQUISA A pesquisa permite também que filtremos informações por qualquer campo da entidade sendo pesquisada através da URL Exemplo GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml?active=true
  36. 36. APROFUDANDO A PESQUISA Permite ainda pesquisas por campos de entidades relacionadas ao recurso Exemplo GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/ agent.xml?agentType.description=Vendedores
  37. 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
  38. 38. EXEMPLO DE VISUALIZAÇÃO Visualizar um agente: GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml 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
  39. 39. EXEMPLO DE INCLUSÃO Incluir um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml 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> Nome do recurso operado Identificador do novo agente Dados do agente a ser incluso Link para acesso ao novo agente
  40. 40. EXEMPLO DE ALTERAÇÃO Alterar um agente: POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml Envio: <agent> <name>Novo Nome</name> </agent> Resposta: <result> <resourceName>agent</resourceName> <resourceId>1234</resourceId> <link>/agent/1234.xml</link> </result> Nome do recurso operado Dados do agente a ser alterado (apenas os dados a serem modificados) Identificador do agente alterado Link para acesso ao agente alterado
  41. 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
  42. 42. EXEMPLO IDENTIFICADOR ALTERNATIVO O início da URL (http://api.umov.me/CenterWeb) foi omitida nos exemplos abaixo Visualizar um agente: GET: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml Alterar um agente: POST: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml
  43. 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
  44. 44. EXEMPLO DE ERRO Retorno: <result> <statusCode>400</statusCode> Código de erro http retornado <errors>login: error.mandatory.field</errors> Campo e mensagem de erro <resourceName>agent</resourceName> Recurso manipulado pela requisição </result>
  45. 45. OBRIGADO @nbluis http://about.me/nbluis

×