uMov.me API - Do básico ao avançado
-
Upload
eduardo-bohrer -
Category
Technology
-
view
1.450 -
download
7
description
Transcript of uMov.me API - Do básico ao avançado
![Page 1: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/1.jpg)
UMOV.ME APIDo básico ao avançado
@nbluishttp://about.me/nbluis
![Page 2: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/2.jpg)
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
![Page 3: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/3.jpg)
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
![Page 4: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/4.jpg)
COMO FUNCIONA ?
• Através de requisições HTTP
• Trafega informação por XML
• Utiliza conceitos de REST
![Page 5: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/5.jpg)
COMO FUNCIONA ?
• Através de requisições HTTP
• Trafega informação por XML
• Utiliza conceitos de REST
![Page 6: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/6.jpg)
ENTENDENDO HTTP
HTTP é o protocolo padrão utilizado na internet
É através de HTTP que nosso navegador acessa qualquer site na internet
![Page 7: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/7.jpg)
ENTENDENDO HTTP
Cliente ServidorRequisição / Request
Resposta / Response
http://api.umov.me
Conteúdo da resposta
![Page 8: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/8.jpg)
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)
![Page 9: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/9.jpg)
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)
![Page 10: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/10.jpg)
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.
![Page 11: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/11.jpg)
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
![Page 12: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/12.jpg)
COMO FUNCIONA ?
• Através de requisições HTTP
• Trafega informação por XML
• Utiliza conceitos de REST
![Page 13: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/13.jpg)
ENTENDENDO XML
• É uma linguagem de marcação
• Baseado em tags
• Facil de representar estruturas complexas utilizando texto
• Todo mundo conhece
![Page 14: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/14.jpg)
EXEMPLO DE XML<carro> <marca>Fiat</marca> <modelo>Uno</modelo> <ano>2013</ano> <portas>2</portas> <utilitarios> <utilitario nome=”Vidro Elétrico”/> </utilitarios></carro>
![Page 15: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/15.jpg)
COMO FUNCIONA ?
• Através de requisições HTTP
• Trafega informação por XML
• Utiliza conceitos de REST
![Page 16: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/16.jpg)
ENTENDENDO REST
Um serviço REST nada mais é que utilizar o que já aprendemos sobre HTTP para manusear este serviço.
![Page 17: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/17.jpg)
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>
![Page 18: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/18.jpg)
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
![Page 19: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/19.jpg)
CRIANDO UM TOKEN
Para criar um TOKEN para um ambiente basta acessar a tela de “Criação > Parâmetros” no uMov.Center
![Page 20: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/20.jpg)
EXEMPLO DE ACESSO A APIGET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
![Page 21: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/21.jpg)
EXEMPLO DE ACESSO A APIGET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Método HTTP
![Page 22: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/22.jpg)
EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
URL Base
GET:
![Page 23: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/23.jpg)
EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Token de acesso
GET:
![Page 24: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/24.jpg)
EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Recurso acessado
GET:
![Page 25: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/25.jpg)
EXEMPLO DE ACESSO A APIhttp://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Formato (apenas xml)
GET:
![Page 26: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/26.jpg)
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.
![Page 27: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/27.jpg)
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
![Page 28: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/28.jpg)
EXEMPLO DE ACESSO A API
Fique atento aos pontos destacados em cada operação
![Page 29: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/29.jpg)
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:
![Page 30: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/30.jpg)
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:
![Page 31: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/31.jpg)
EXEMPLO DE ACESSO A API
Para a maioria das demais operações basta alterar o recurso na URL
![Page 32: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/32.jpg)
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
![Page 33: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/33.jpg)
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.
![Page 34: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/34.jpg)
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
![Page 35: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/35.jpg)
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
![Page 36: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/36.jpg)
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
![Page 37: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/37.jpg)
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
![Page 38: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/38.jpg)
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
![Page 39: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/39.jpg)
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>[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 inclusoLink para acesso ao novo agente
Identificador do novo agente
Nome do recurso operado
![Page 40: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/40.jpg)
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
![Page 41: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/41.jpg)
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
![Page 42: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/42.jpg)
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
![Page 43: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/43.jpg)
VISUALIZANDO ERROS
Sempre que ocorrer o erro em decorrência de uma requisição, a mensagem será retornada permitindo um
melhor entendimento do problema
![Page 44: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/44.jpg)
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
![Page 45: uMov.me API - Do básico ao avançado](https://reader035.fdocument.pub/reader035/viewer/2022081720/5597d9a61a28abae5e8b46c4/html5/thumbnails/45.jpg)
OBRIGADO
@nbluishttp://about.me/nbluis