umov.me api - do básico ao avançado

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 ?

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 ?

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 ?

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

Método HTTP

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

URL Base

Token de acesso

Recurso acessado

Formato (apenas xml)

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.

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

Fique atento aos pontos destacados em cada operação

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

o seu id.

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

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

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

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

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

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

umov.me api - do básico ao avançado

Technology

opengl alberto b. raposo . opengl: o que é? api...

catalogo api 5l

opendata api

folder api refeito

relatorio api

sql api java

api do twitter

api agregadas

umov.me - mobilidade a serviço do seu negócio

apostila api win32

norma api 650

moodle api tutorial

api 653-2009

relatorio api final

html5 storage api

asp.net web api

api umov2015/10/13 · api umov.me este documento descreve...

apresentacao api

gewinde - erich thieme gmbh...= trapezoidal, din103 = am....

din api spec5lx