A plataforma CKAN está disponível também através de sua API (Application Programming Interface) que
fornece acesso programático para o sistema CKAN. A API é muito poderosa e permite que você faça tudo
(e muito mais) que você pode fazer através da interface web.
Usando a API você pode fazer coisas como:




Acessar qualquer bit de informação no CKAN
Alterar qualquer pedaço de informação no CKAN (se você estiver autorizado!)
Criar um novo front-end web inteiro para o CKAN (se quiser!)
A API CKAN segue o estilo RESTful (Transferência de Estado Representativo) e usa JSON por
padrão.
Ao usar a API, você estará realizando solicitações HTTP para URLs como /api/rest/dataset, que retornam
dados em formato JSON.
Existem várias maneiras que você pode acessar esta URL diretamente:
·
Coloque este URL no seu navegador e veja o resultado. Existem plugins para navegadores como
o Firefox e o Chrome que lhe permitem visualizar corretamente arquivos em formato JSON no seu
navegador (por exemplo, JSONView para o Chrome )
·
Use um programa de linha de comando, como onda
·
Escreva um programa em sua linguagem de programação favorita com uma biblioteca de http
para acessar o URL
Alternativamente, você pode acessar a API usando uma das ferramentas dedicadas ou bibliotecas
escritas especificamente para o CKAN. Os seguintes clientes estão disponíveis:
dpm (gerenciador de pacotes de dados) : cliente de linha de comando e uma biblioteca Python (mantidos pela
equipe do núcleo do CKAN)
ckanclient - CKAN Python Cliente : Python (mantido pela equipe do núcleo CKAN)
CKAN Ruby : Ruby
Ckan_client-PHP : PHP
Ckan_client-J : Java
net-CKAN : PERL
ckanjs : Javascript (BackboneJS)
Extensão CKAN Google Refine : o cliente Google Refine lhe permite obter e enviar dados de e para uma
instância CKAN usando o Google Refine.
Para atender os scripts de outros sites ou aplicativos que desejam acessar a API, os dados podem ser
retornados em formato JSONP, onde o dado JSON é "preenchido" com uma chamada de função. A
função é chamada no parâmetro "callback".
Exemplo de pedido normal:
GET
http://catalogo.seplande.al.gov.br/api/rest/dataset/percentual-de-domicilios-particulares-permanentes-com-televisao
retorna: {"name": "Percentual de domicílios
televisão - dados totais de Alagoas ", ...}
particulares
permanentes
com
Exemplo de pedido com callback:
GET
http://catalogo.seplande.al.gov.br/api/rest/dataset/percentual-de-domicilios-particulares-permanentes-com-televisao?callback=json
retorna: json ({"name": "Percentual de domicílios particulares permanentes com
televisão - dados totais de Alagoas", ...});
Este parâmetro pode ser aplicado a todas as requisições GET para a API Search e APIs v1/v2/v3.
O localizador para determinado resource pode ser formado adicionando o caminho relative do resource ao
localizador da API.
Resource Locator = API Locator + Resource Path
Os localizadores para API do CKAN (por versão) são:
·
/api (versão 1)
·
/api/1 (versão 1)
·
/api/2 (versão 2)
Códigos padrão http são utilizados para sinalizar respostas.
Tabela 1 – Códigos de retorno da API CKAN
CÓDIGO
STATUS
200
OK
201
OK and new object created (referred to in the Location header)
301
Moved Permanently
400
Bad Request
403
Not Authorized
404
Not Found
409
Conflict (e.g. name already exists)
500
Service Error
Fonte: Documentação da API do CKAN 1.7.2
Modelos de resources estão disponíveis. Eles são representados por uma variedade de formatos de dados.
Cada local de recursos suporta um número de métodos.
Tabela 2 – Modelos de Resources
MODELO DE RESOURCE
OCALIZAÇÃO
Dataset Register
/rest/dataset
Dataset Entity
/rest/dataset/DATASET-REF
Group Register
/rest/group
Group Entity
/rest/group/GROUP-REF
Tag Register
/rest/tag
Tag Entity
/rest/tag/TAG-NAME
Rating Register
/rest/rating
Dataset Relationships Register
/rest/dataset/DATASET-REF/relationships
Dataset Relationships Register
/rest/dataset/DATASET-REF/RELATIONSHIP-TYPE
Dataset Relationships Register
/rest/dataset/DATASET-REF/relationships/DATASET-REF
Dataset Relationship Entity
/rest/dataset/DATASET-REF/RELATIONSHIP-TYPE/DATASET-REF
Dataset’s Revisions Entity
/rest/dataset/DATASET-REF/revisions
Revision Register
/rest/revision
Revision Entity
/rest/revision/REVISION-ID
License List
/rest/licenses
Fonte: Documentação da API do CKAN 1.7.2
Os valores possíveis para DATASET-REF são ID do dataset, ou o nome do dataset atual.
Os valores possíveis para RELATIONSHIP-TYPE são descritos no formato de dados Relationship-Type.
Em geral:
·
GET a um resource de registro irá listar as entidades desse tipo.
·
GET de um resource entidade irá mostrar as propriedades da entidade.
·
POST de dados de entidade para um resource registo irá criar a nova entidade.
·
PUT de dados de entidade para um resource entidade existente irá atualizá -lo.
Tabela 3 – Formato de dados para a API Model
NOME
FORMATO
Dataset-Ref
Dataset-Name-String (API v1) OR Dataset-Id-Uuid (API v2)
Dataset-List
[ Dataset-Ref, Dataset-Ref, Dataset-Ref, ... ]
{ id: Uuid, name: Name-String, title: String, version: String, url: String, resources: [ Resource, Resource, ...], author:
Dataset
String, author_email: String, maintainer: String, maintainer_email: String, license_id: String, tags: Tag-List, notes: String,
extras: { Name-String: String, ... } } See note below on additional fields upon GET of a dataset.
Group-Ref
Group-Name-String (API v1) OR Group-Id-Uuid (API v2)
Group-List
[ Group-Ref, Group-Ref, Group-Ref, ... ]
Group
{ name: Group-Name-String, title: String, description: String, packages: Dataset-List }
Tag-List
[ Name-String, Name-String, Name-String, ... ]
Tag
{ name: Name-String }
Resource
{ url: String, format: String, description: String, hash: String }
Rating
{ dataset: Name-String, rating: int }
NOME
FORMATO
Pkg-
[ Pkg-Relationship, Pkg-Relationship, ... ]
Relationships
Pkg-
{ subject: Dataset-Name-String, object: Dataset-Name-String, type: Relationship-Type, comment: String }
Relationship
Pkg-Revisions [ Pkg-Revision, Pkg-Revision, Pkg-Revision, ... ]
Pkg-Revision { id: Uuid, message: String, author: String, timestamp: Date-Time }
Relationship- One of: ‘depends_on’, ‘dependency_of’, ‘derives_from’, ‘has_derivation’, ‘child_of’, ‘parent_of’, ‘links_to’,
Type
‘linked_from’.
Revision-List [ revision_id, revision_id, revision_id, ... ]
Revision
{ id: Uuid, message: String, author: String, timestamp: Date-Time, datasets: Dataset-List }
License-List
[ License, License, License, ... ]
License
{ id: Name-String, title: String, is_okd_compliant: Boolean, is_osi_compliant: Boolean, tags: Tag-List, family: String, url:
String, maintainer: String, date_created: Date-Time, status: String }
Fonte: Documentação CKAN API 1.7.2
Para enviar dados de solicitação, criar a string JSON (codificar em UTF8),
colocá-la no corpo da
solicitação e enviar usando PUT ou POST.
Os dados requisitados estarão no corpo da resposta em formato JSON.
Notas:
·
Quando você atualizar um objeto, os campos que você não fornecer permanecerão como eram
antes.
·
·
Para excluir um par chave-valor "extra", fornecer a chave com valor JSON: null
Quando você lê um conjunto de dados, algumas informações adicionais são fornecidas que
você não pode modificar e enviar de volta para a API. Estes campos 'somente leitura' são fornecidos
somente no Dataset GET. São eles:
Tabela 4 – Campos somente leitura do Dataset
CHAVE
DESCRIÇÃO
id
Identificador único do Dataset
revision_id
Identificador da última revisão do pacote
metadata_created
Data de criação do Dataset
metadata_modified
Data da última modificação no Dataset
relationships
Informações sobre os relacionamentos do Dataset
ratings_average
ratings_count
ckan_url
download_url (API v1)
URL completa do Dataset
URL do primeiro resource
isopen
Indicador booleano se o Dataset é aberto de acordo com o Open Knowledge Definition
notes_rendered
Versão HTML do campo de Notas (pode conter código de marcação)
Fonte: Documentação CKAN API 1.7.2
Disponibilizamos uma pequena aplicação JavaScript onde é feita a consulta a API.
Clique aqui para acessá-la.
Ou baixe o código fonte.