Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
325 lines (269 sloc) 9.96 KB

Documentacao da API

Esta página reúne alguns exmeplos de uso da API, em especial dos métodos de busca por entidades.

A documentação completa de todos os endpoints está sendo construída aqui: http://docs.mapasculturais.org/apidoc/index.html?doctype=api

Exemplos de uso.

Para tornar mais fácil a leitura dos exemplos será utilizada a função getJSON do jQuery.

  • retornando o nome do espaço de id 10
$.getJSON(
  'http://mapasculturais.local/api/space/find',
  {
    '@select': 'name',
    'id': 'eq(10)'
  },
  function (response){ console.log(response); });
  • retornando o id, nome e email dos agentes com email do google
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, email',
    'email': 'like(*gmail.com)'
  },
  function (response){ console.log(response); });
  • retornando o id e nome do espaços e nomes do agentes que publicaram os espaços
$.getJSON(
  'http://mapasculturais.local/api/space/find',
  {
    '@select': 'id, name, owner.name',
  },
  function (response){ console.log(response); });
  • retornando o id e nome dos agentes com email do google ou do yahoo
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    'emailPublico': 'OR(like(*gmail.com), like(*yahoo.com))'
  },
  function (response){ console.log(response); });
  • retornando o id, nome dos agentes com com id entre 100 e 200, exceto o de id 150
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    'id': 'AND(BET(100,200), !EQ(150))'
  },
  function (response){ console.log(response); });
  • retornando o id e nome dos agentes com com id entre 100 e 200, exceto o de id 150 e que tenham email do google ordenado pela data de criação do agente
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    '@order': 'createTimestamp ASC',
    'id': 'AND(BET(100,200), !EQ(150))',
    'emailPublico': 'OR(like(*gmail.com), like(*yahoo.com))'
  },
  function (response){ console.log(response); });
  • retornando o id e nome dos agentes com com id entre 100 e 200, exceto o de id 150 OU que tenham email do google ordenado pelo nome descendentemente
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    '@order': 'name DESC',
    '@or': 1,
    'id': 'AND(BET(100,200), !EQ(150))',
    'emailPublico': 'OR(like(*gmail.com), like(*yahoo.com))'
  },
  function (response){ console.log(response); });
  • retornando a segunda página de 10 agentes ordenado pelo nome
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, files',
    '@order': 'name ASC',
    '@limit': 10,
    '@page': 2
  },
  function (response){ console.log(response); });
  • retornando a segunda página de 10 agentes ordenado pelo nome com a url do avatar, url do thumbnail do avatar e todos os downloads
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    '@order': 'name ASC',
    '@limit': 10,
    '@page': 2,
    '@files': '(avatar,avatar.avatarSmall,downloads):url'
  },
  function (response){ console.log(response); });
  • retornando as entidades próximas a latitude -23.5413271705055 e longitude -46.6475415229797
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, location',
    '@order': 'name ASC',
    '_geoLocation': 'GEONEAR(-46.6475415229797,-23.5413271705055,700)'
  },
  function (response){ console.log(response); });
  • retornando o id, nome dos eventos e sua lista de ocorrências contendo id, nome do local e o objeto rule das mesmas. No objeto rules, há o campo description, que contém uma versão legível para humanos da data, horários e frequência da ocorrência. A busca filtra eventos de id entre 100 e 200.
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name,occurrences.{id,space.{name},rule}',
    'id': 'BET(100,200)'
  },
  function (response){ console.log(response); });
  • retornando o id, nome dos eventos e o objeto terms, que agrupa taxonomias, neste caso linguagens (cada entidade tem as suas taxonomias). A busca filtra eventos que tenham a linguagem LIKE 'Cinema' e possuam id entre 100 e 200.
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name,terms' ,
    'term:linguagem': 'LIKE(Cinema)',
    'id': 'BET(100,200)'    
  },
  function (response){ console.log(response); });
  • retornando o id, nome e a descrição curta dos eventos, junto com os endereços (URL) para os arquivos do header e avatar. A busca filtra eventos de id entre 100 e 200.
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@files': 'header.header, avatar.avatarBig',
    '@select': 'id, name, shortDescription',
    'id': 'BET(100,200)'
  },
  function (response){ console.log(response); });
  • retornando a versão atual da instalação do mapasculturais.
$.getJSON(
  'http://mapasculturais.local/api/site/version',
  function (response){ console.log(response); });

Filtrando por relacionamentos

  • Selecionando todos os espaços do agente de id 1
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, location',
    '@order': 'name ASC',
    'owner': 'EQ(@Agent:1)'
  },
  function (response){ console.log(response); });
  • Selecionando todos os eventos do projeto de id 4
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name, location',
    '@order': 'name ASC',
    'project': 'EQ(@Project:4)'
  },
  function (response){ console.log(response); });

API de Escrita

Para conseguir criar, atualizar ou apagar entidades via API, primeiramente é necessário cadastrar o seu App indo no painel de usuário do Mapas Culturais e acessando "Meus Apps". Após criar um novo App, copie as duas chaves que são fornecidas (Pública e Prvada). A API de escrita do Mapas utiliza o padrão de JSON Web Tokens - JWT para identificar de maneira segura dois sistemas que queiram se comunicar.

Criando o JWT

Um JWT é formado de 3 partes - Header, Payload e Assinatura - encodadas com a função base64UrlEncode(1) concatenadas utilizando um ponto (.) como aglutinador.

1 - é um base64encode fazendo as seguintes subsituições na string:

  '=' -> '' // remove os caracteres '='
  '+ -> '-'
  '/' -> '_'

Header

O Header do JWT geralmente consiste em informar o tipo do token (JWT!) e o algorítimo de hash utilizado. Para a API do Mapas Culturais o header deve seguir o formato abaixo, utilizando um dos seguintes algorítmos de hash: HS512, HS384, HS256, RS256.

{
  "typ": "JWT",
  "alg": "HS256"
}

resultado do base64encode: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

Payload

O Payload deve conter sua chave pública, identificada como "pk" e um timestamp(1) "tm" que é um timestamp Unix em microsegundos do momento em que a requisição foi enviada.

{
  "tm": "1493823078.9774",
  "pk": "chave publica"
}

resultado do base64encode: eyJ0bSI6IjE0OTM4MjMwNzguOTc3NCIsInBrIjoiY2hhdmUgcHVibGljYSJ9

_1 - O timestamp é opcional, mas serve como um salt para empedir que o token gerado seja sempre o mesmo.

Assinatura

A assinatura do JWT é o base64UrlEncode do resultado da concatenação do header e do payload (ambos encodados com o base64UrlEncode e utilizando um ponto como aglutinador) criptografado utilizando o hash informado no header com sua chave privada.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  'chave privada'
)

resultado do base64UrlEncode: 3UAdCFaqi1GkVMebr1a0WdOLc1QUUKPNlwlEXjb2peg

Resultado

O Token gerado para um momento de timestamp 1493823078.9774 e chaves: chave publica e chave privada é eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0bSI6IjE0OTM4MjMwNzguOTc3NCIsInBrIjoiY2hhdmUgcHVibGljYSJ9.3UAdCFaqi1GkVMebr1a0WdOLc1QUUKPNlwlEXjb2peg

Fazendo requisições

Toda requisição feita deve conter duas informações no seu header: o valor do JWT no header "authorization" e um header "MapasSDK-REQUEST" com valor "true"

"authorization": eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0bSI6IjE0OTM4MjMwNzguOTc3NCIsInBrIjoiY2hhdmUgcHVibGljYSJ9.3UAdCFaqi1GkVMebr1a0WdOLc1QUUKPNlwlEXjb2peg,
"MapasSDK-REQUEST": true

Visite a documentação da API para a lista completa para os endpoints para criar, atualizar e apagar entidades.

SDK

Se você estiver desenvolvendo uma aplicação em PHP, há uma SDK que pode deixar as coisas bem mais fáceis.

Acesse o projeto do Github da SDK e veja arquivo de exemplo sobre como a utilizar.

Exemplos

  • criando um agente
$data = [
    'type' => '2',
    'name' => 'Fulano ' . date('Y/m/d H:i:s'),
    'shortDescription' => 'Oi',
    'terms' => [
        'area' => [
            'Arqueologia'
        ]
    ],
    'location' => [
        '-46.685684400000014',
        '-23.5404024'
    ],
    'endereco' => 'Rua Capital Federal'
];

$curl->setHeader('authorization', $jwt);
$curl->setHeader('MapasSDK-REQUEST', true);

$curl->post('http://mapas.cultura.gov.br/agent/index', $data);
$curl->close();
  • alterando um agente
$data = [
    shortDescription => 'Description'
];

$curl->setHeader('authorization', $jwt);
$curl->setHeader('MapasSDK-REQUEST', true);

$curl->patch('http://mapas.cultura.gov.br/agent/single/35', $data);
$curl->close();
  • apagando um espaço
$curl->setHeader('authorization', $jwt);
$curl->setHeader('MapasSDK-REQUEST', true);

$curl->delete('http://mapas.cultura.gov.br/space/single/8');
$curl->close();
You can’t perform that action at this time.