Documentacao da API

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

Action find

Parâmetros O Método find aceita os seguintes parâmetros:

Operadores

Para filtrar os resultados o método find aceita os seguintes operadores em qualquer das propriedades e metadados das entidades:

Exemplos de uso.

$.getJSON(
  'http://mapasculturais.local/api/space/find',
  {
    '@select': 'name',
    'id': 'eq(10)'
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, email',
    'email': 'like(*gmail.com)'
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/space/find',
  {
    '@select': 'id, name, owner.name',
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    'emailPublico': 'OR(like(*gmail.com), like(*yahoo.com))'
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name',
    'id': 'AND(BET(100,200), !EQ(150))'
  },
  function (response){ console.log(response); });
$.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); });
$.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); });
$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, files',
    '@order': 'name ASC',
    '@limit': 10,
    '@page': 2
  },
  function (response){ console.log(response); });
$.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); });
$.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); });
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name,occurrences.{id,space.{name},rule}',
    'id': 'BET(100,200)'
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name,terms' ,
    'term:linguagem': 'LIKE(Cinema)',
    'id': 'BET(100,200)'    
  },
  function (response){ console.log(response); });
$.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); });

Filtrando por relacionamentos

$.getJSON(
  'http://mapasculturais.local/api/agent/find',
  {
    '@select': 'id, name, location',
    '@order': 'name ASC',
    'owner': 'EQ(@Agent:1)'
  },
  function (response){ console.log(response); });
$.getJSON(
  'http://mapasculturais.local/api/event/find',
  {
    '@select': 'id, name, location',
    '@order': 'name ASC',
    'project': 'EQ(@Project:4)'
  },
  function (response){ console.log(response); });

Action describe

Retorna a descrição de entidade.

$.getJSON(
  'http://mapasculturais.local/api/event/describe',
  function (response){ console.log(response); });

// output:
{
   "id":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"integer",
      "length":null
   },
   "location":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"point",
      "length":null
   },
   "name":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"string",
      "length":255
   },
   "shortDescription":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":false,
      "type":"text",
      "length":null
   },
   "longDescription":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":false,
      "type":"text",
      "length":null
   },
   "certificateText":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":false,
      "type":"text",
      "length":null
   },
   "createTimestamp":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"datetime",
      "length":null
   },
   "status":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"smallint",
      "length":null
   },
   "_type":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"smallint",
      "length":null,
      "@select":"type"
   },
   "isVerified":{
      "isMetadata":false,
      "isEntityRelation":false,
      "required":true,
      "type":"boolean",
      "length":null
   },
   "parent":{
      "isMetadata":false,
      "isEntityRelation":true,
      "targetEntity":"Space",
      "isOwningSide":true
   },
   "children":{
      "isMetadata":false,
      "isEntityRelation":true,
      "targetEntity":"Space",
      "isOwningSide":false
   },
   "owner":{
      "isMetadata":false,
      "isEntityRelation":true,
      "targetEntity":"Agent",
      "isOwningSide":true
   },
   "emailPublico":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Email Público",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "emailPrivado":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Email Privado",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "telefonePublico":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Telefone Público",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "telefone1":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Telefone 1",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "telefone2":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Telefone 2",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "acessibilidade":{
      "required":false,
      "type":"select",
      "length":null,
      "private":false,
      "options":{
         "":"Não Informado",
         "Sim":"Sim",
         "Não":"Não"
      },
      "label":"Acessibilidade",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "capacidade":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Capacidade",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "endereco":{
      "required":false,
      "type":"text",
      "length":null,
      "private":false,
      "label":"Endereço",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "horario":{
      "required":false,
      "type":"text",
      "length":null,
      "private":false,
      "label":"Horário de funcionamento",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "criterios":{
      "required":false,
      "type":"text",
      "length":null,
      "private":false,
      "label":"Critérios de uso do espaço",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "site":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Site",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "facebook":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Facebook",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "twitter":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Twitter",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "googleplus":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Google+",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "sp_regiao":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Região",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "sp_subprefeitura":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Subprefeitura",
      "isMetadata":true,
      "isEntityRelation":false
   },
   "sp_distrito":{
      "required":false,
      "type":"string",
      "length":null,
      "private":false,
      "label":"Distrito",
      "isMetadata":true,
      "isEntityRelation":false
   },
    "@file": {
        "header": [
            "header"
        ],
        "avatar": [
            "avatar",
            "avatarSmall",
            "avatarMedium",
            "avatarBig",
            "avatarEvent"
        ],
        "downloads": [
            "downloads"
        ],
        "gallery": [
            "gallery",
            "galleryThumb",
            "galleryFull"
        ]
    }
}

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 '='
  '+ -> '-'
  '/' -> '_'

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

Os métodos da API são, lembrando que os tipos de entidade são Agent, Space, Project, Event, Subsite, Seal:

createEntity

Caminho: "\/index"

Tipo da requisição: POST

Esse método é utilizado para criar um novo registro para uma Entidade, os dados da entidade a ser criada devem ser enviados no body da requisição.

patchEntity

Caminho: "\/single/\"

Tipo da requisição: PATCH

Esse método deve ser usado para alterações parciais de dados de um registro de uma certa Entidade.

updateEntity

Caminho: "\/single/\"

Tipo da requisição: PUT

Esse método é usado para alteração de dados de um único registro. Atenção: Todos os dados da entidade devem estar na requisição, inclusive aqueles que não serão alterados.

deleteEntity

Caminho: "\/single/\"

Tipo da requisição: DELETE

Apaga o registro informado.

Exemplos:

$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();
$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();
$curl->setHeader('authorization', $jwt);
$curl->setHeader('MapasSDK-REQUEST', true);

$curl->delete('http://mapas.cultura.gov.br/space/single/8');
$curl->close();