Acesso e Autenticação

Tudo o que você precisa saber para integrar nossa API no seu aplicativo

Cadastrando o Aplicativo

Basta completar o formulário de cadastro e o aplicativo ganhará o consumer key e consumer secret, que fazem o papel de "usuário" e "senha" dele na API.

Você pode consultar esses dados a qualquer momento no seu perfil no Apontador.

Chamando a API

A API é um serviço REST: todas as chamadas são feitas através de conexões HTTP no endereço api.apontador.com.br e prefixadas pelo identificador da versão (a atual é a v1).

Ou seja, para acessar o método categories, chame: http://api.apontador.com.br/v1/categories.

Experimente no navegador:

Clique aqui e forneça o key como usuário e o secret como senha.

Experimente em PHP:

<html>
  <pre>
    <?php
      // Usamos file_get_contents só para demonstrar - não é 100% recomendado ou aceito
      // pelos servidores. Recomendação: http://php.net/manual/pt_BR/book.curl.php
      $key = "COLOQUE_SEU_CONSUMER_KEY_AQUI";
      $secret = "COLOQUE_SEU_CONSUMER_SECRET_AQUI";
      $chamada = "http://$key:$secret@api.apontador.com.br/v1/categories?type=json";
      $resultado = json_decode(file_get_contents($chamada));
      var_dump($resultado);
    ?>
  </pre>
</html>

Parâmetros e Retorno

As chamadas da API recebem seus parâmetros conforme o verbo HTTP (ex.: na URL para GET, no corpo para POST). Você escolhe se quer o retorno em XML (default) ou JSON (adicionando o parâmetro type=json).

O encoding é sempre UTF-8, e parâmetros na URL devem representar os bytes UTF-8 com "%-encode".

Autenticando: HTTP Basic

Para chamadas que não envolvem outros usuários do Apontador (ex.: busca de locais), seu aplicativo pode usar a autenticação HTTP Basic - que é o que o navegador fez no exemplo acima.

Exemplo: digamos que o consumer key do aplicativo é 123456 e o consumer secret é ABCDEF. Obtenha o valor de "123456:ABCDEF" em Base64 e inclua no header Authorization ao chamar a API, isto é:

Authorization: Basic MTIzNDU2OkFCQ0RFRg==

Autenticando: OAuth

Chamadas que exigem autorização prévia do usuário, para que o seu aplicativo possa agir em nome dele (exemplos: postar avaliações, inserir locais). Para isso você vai usar OAuth, e sugerimos que escolha uma biblioteca entre as opções disponíveis para a sua linguagem de programação.

A biblioteca vai pedir as URLs abaixo, conforme a especificação:

Request Token URL:
http://api.apontador.com.br/v1/oauth/request_token
User Authorization URL:
http://api.apontador.com.br/v1/oauth/authorize
Access Token URL:
http://api.apontador.com.br/v1/oauth/access_token

Seu fluxo deve ser desenhado de forma que, caso o aplicativo não tenha em mãos os tokens de acesso (ou se eles não forem válidos), o usuário seja levado à tela de confirmação de acesso no Apontador.

Consulte a documentação da biblioteca - o processo costuma ser automático, e você só terá que disponibilizar um endereço de retorno (callback) para receber os tokens (e guardá-los para acesso direto dali em diante).

Caso prefira implementar manualmente este fluxo de autenticação, siga as orientações da especificação OAuth.

Chamando via JavaScript (novidade!)

Também é possível chamar os métodos Basic da API diretamente de uma página, usando JavaScript.

Para habilitar este modo você deve preencher o campo "Endereço (URL) do site do Aplicativo" no cadastro do mesmo - a API só aceita pedidos vindos de páginas hospedadas no mesmo host desta URL.

Segue um exemplo de chamada usando a biblioteca JQuery:

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <script type="text/javascript" src=
      "http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
    <script type="text/javascript">
      $.getJSON("https://api.apontador.com.br/v1/search/places/byaddress?callback=?", {
        jsconsumerkey : "COLOQUE_SEU_CONSUMER_KEY_AQUI",
        type : "jsonp",
        city : "Sao Paulo",
        state : "SP",
        term : "Fiesp"
      }, function(data) {
        if (data.search.places.length>0) {
          var place = data.search.places[0].place;
          alert(place.name + "," + place.category.name);
        }
      });
    </script>
  </head>
</html>

É importante declarar o charset, passar os parâmetros (jsconsumerkey e type=jsonp) e adicionar o ?callback=? na URL. Com isso, o JQuery processa a função de padding do JSONP automaticamente.

Se preferir usar JavaScript "puro", siga este exemplo do Dirceu Pauka Jr.

OAuth sem Servidor (via PIN)

Aplicativos web efetuam a autorização do usuário redirecionando seu navegador para a User Authorization URL (vide acima) e aguardando que ele retorne através do endereço de callback.

Este processo é pouco viável para aplicativos desktop ou em celulares, que não dispõem de um servidor para hospedar este endereço de callback (e nem sempre podem abrir um navegador sem fechar o aplicativo).

A solução nestes casos é fácil: edite os dados do aplicativo no Apontador, informando a seguinte URL de callback:

http://api.apontador.com.br/v1/oauth/callback

Quando for pedir a autorização de um usuário, faça o processo normal, mas chame a User Authorization URL via http, da mesma forma que você chamou a Request Token URL. O retorno dela será uma URL curta, que o seu aplicativo pode abrir em um browser (e/ou pedir para o usuário abrir).

Este callback também fará com que o usuário receba um PIN code, isto é, um número que ele digitará no seu aplicativo. Ela usará este número no lugar do oauth_verifier e seguirá o processo normal, guardando o token e secret finais (que serão usados para chamar a API em nome) localmente.

Tratamento de Erros

Caso a requisição não possa ser atendida por algum motivo, a API retorna a seguinte estrutura (ou sua equivalente JSON), permitindo ao aplicativo verificar a existência do atributo code antes de processar o retorno:

<error>
  <code>1</code>
  <message>Descrição amigável do erro</message>
</error>

Compatibilidade com o Futuro

A API deve ganhar mais funcionalidades ao longo do tempo. Para garantir a compatibilidade com essas mudanças não assuma que os parâmetros do retorno manterão a mesma ordem que apresentam hoje, e considere que podem vir novos parâmetros junto com os atuais.

Estes simples cuidados asseguram a compatibilidade futura, já que a hierarquia dos dados retornados, bem como seus nomes, formatos e obrigatoriedade atuais serão sempre mantidos nas URLs da versão atual.

Nossa sugestão: transforme o retorno em um objeto, ou use algo como XPath - dessa forma, você acessa os retornos de forma hierárquica, contornando o problema.

E agora?

Agora você está pronto para explorar tudo o que a Apontador API é capaz de fazer - vá em frente!