Anatomía de las APIs del Idescat

contra el apartheid
de los datos
Anatomía de las APIs del Idescat
Xavier Badosa (@badosa)
Instituto de Estadística de Cataluña
Canarias, mayo 2011

Interfaz de programación de aplicaciones

Interacción
Humano
Humano
—

Interacción
Software
—
Humano

Interacción
Software
—
Software

API
Interacción
Software
—
Software

API
Web
http
Interacción
Software
—
Software
en la nube

API
Web
http
Servicios basados en SOAP
Simple Object Access Protocol
Interacción
Software
—
Software
en la nube

API
Web
http
RESTful Web Services
RepresentationalState Transfer
Interacción
Software
—
Software
en la nube

API
Web
http
Protocolo
RESTful Web Services
Arquitectura
RepresentationalState Transfer
Interacción
Software
—
Software
en la nube

85%
15%

“The only reason you’d have only a SOAP API is
because you hate 80% of your addressable market.”
Sam Ramji (Apigee)
85%
15%

Open APIs: State of the Market (John Musser, ProgrammableWeb)
http://www.slideshare.net/jmusser/open-api-ecosystem-overview-december-2010

API
Web

API
Web
Peticiones
Puntos de acceso

API
Web
Peticiones
Puntos de acceso
Métodos

API
Web
Peticiones
Puntos de acceso
Métodos
Leer
GET
Crear
POST
Actualizar
PUT
Eliminar
DELETE

API
Web
Peticiones
Puntos de acceso
Métodos
Autenticación

API
Web
Peticiones
Puntos de acceso
Métodos
Autenticación
Identidad
Autenticación
Autorización

API
Web
Peticiones
Puntos de acceso
Métodos
Autenticación
Restriccionestécnicas

API
Web
Respuestas
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Características de las APIs del Idescat
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Características de las APIs del Idescat
Puntos de acceso
Formatos
definidas en
2008
Métodos
Autenticación

Puntos de acceso

http://api.idescat.cat
Puntos de acceso

/servicio

/servicio
/versión

/servicio
/versión
/operación

/servicio
/versión
/operación
.formato

/servicio
/versión
/operación
.formato
?parámetros

/servicio
/versión
/operación
.formato
?parámetros
http://api.idescat.cat/pob/v1/cerca.xml?q=abrera

Independencia de interfaz

Independencia de recursos

Independencia de recursos
Limitación del uso interno en contextos
sometidos a la política del mismo origen
(p.e., Ajax)

JSONP
JSON withpadding

Diversidad de soluciones (APIs)

Ausencia de una interfaz unificada

(Simplificar las operaciones)

(publicables gradualmente)

Una API mala es mejor que ninguna API

Una buena API no harábueno un mal servicio

Una buena API no harábueno un mal servicio
“Aunque la mona se vista de seda, mona se queda.”

Permanencia

Permanencia
Una API es un contrato

Permanencia
“PublicAPIsareforever”
Joshua Bloch

Permanencia
indefinido
Joshua Bloch

Permanencia
indefinido
Joshua Bloch
Versión 1.01: ampliación que no rompe la API

Diversidad de operaciones

Vocabulariorestringido

(que en parte determina
la estructura de la respuesta)

“An API is a littlelanguage”
Joshua Bloch

“An API is a littlelanguage”
Joshua Bloch
¿Vocabularioambiguo?

nodes
Dame los nodos
¿Qué recursos (objetos, elementos, átomos) hay?
¿Cómo se clasifican? ¿Quétiposhay? ¿Cómo se identifican?
Dame la lista de recursos

nodes
http://api.idescat.cat/pob/v1/cerca.json?q=abrera

dades
Dame los datos asociados a un nodo(s)
¿Cuáles son los datos y metadatosasociados a un recurso?
Dame (la información de) un recurso
Suele requerir conocersu identificador
nodes

dades
nodes

cerca
Dame los resultados de una búsqueda
¿Cuáles son los recursos que cumplen una búsquedaabierta?
Suele requerir especificar una cadena o algúntipo de filtro.
Puede ser sustitutivo de nodes si hay un número grande
de ellos.
nodes
dades

cerca
nodes
dades

cerca
Atom
nodes
dades

cerca
Atom
OpenSearchResponse
nodes
dades

cerca
Atom
OpenSearchResponse
SDMX
nodes
dades

sug
Sugiéremeliterales de elementos
Suele requerir especificar una cadena o algúntipo de filtro.
Devuelveliteralescompletos, no datos o metadatos.
nodes
dades
cerca

sug
nodes
dades
cerca

sug
OpenSearch Suggestions
nodes
dades
cerca

sug
nodes
dades
cerca

Ajax
Política del mismo origen
sug
nodes
dades
cerca

Ajax
Puentear
http://www.idescat.cat/api/...
sug
nodes
dades
cerca

Dame las categorías
¿Cómo se etiquetan los recursos?
¿Quécategorizacionesexisten y cuáles son suscaracterísticas?
Dame la lista de categorizaciones o categorías
sug
nodes
dades
cerca
categories

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
Formatos
(Una API es un contrato:
el resultado de su uso es
una coproducción)
Métodos
Autenticación

API
Web
XML

API
Web
XML
ecosistema

API
Web
XML
ecosistema
XSLT

API
Web
XML
PHP

API
Web
XML
OpenSocial (JS)

http://google-styleguide.googlecode.com/svn/trunk/xmlstyle.html

http://www.dataspora.com/2009/08/xml-and-big-data/

http://blog.jclark.com/2010/11/xml-vs-web_24.html

https://graph.facebook.com/badosa

Open APIs: State of the Market (John Musser, ProgrammableWeb)
http://www.slideshare.net/jmusser/open-api-ecosystem-overview-december-2010

Elementos = atributos

API
Web
JSON

API
Web
JSON
JS

API
Web
XMLHttpRequest()
JSON
JS

API
Web
P
JSON

callback
API
Web
P
JSON

callback
API
Web
P
JSON
mifuncion({"indicadors":{"p":"tt=0;max=1;min=1;","n":"1","o":"dades" ... })

is_array($o->indicadors->i)
API
Web
PHPserializado

Si no existe un estándar que especifique
una respuesta para cada formato
API
Web

API
Web
XML

API
Web
XML
JSON

API
Web
XML
JSON
PHP
...

API
Web
XML
+ fácilgeneración
+ fácildocumentación
JSON
PHP
...

API
Web
XML
+ fácilgeneración
JSON
XML JSONificado
(o JSON con sabor a XML)
PHP
...

API
Web
XML
+ fácilgeneración
JSON
XML JSONificado
(o JSON con sabor a XML)
PHP
...
...
XML JSONificadoPHPizado

API
Web
XML
JSON
Modelo general de
representación interna
PHP
...

API
Web
XML
Plantillas
JSON
Modelo general de
representación interna
PHP
...
Plantillas

Un caso en el que existe un estándar que
especifica una respuesta para cada formato
API
Web

Un caso en el que existe un estándar que
especifica una respuesta para cada formato
API
Web
OpenSearch
Suggestions

FF:JSON
IE8:XML

FF:JSON
IE8:XML
jquery / Autocomplete: TXT

http://api.idescat.cat/pob/v1/sug.txt?q=ab
jquery / Autocomplete: TXT

/servicio
/versión
/operación
.formato
?parámetros

Parámetros generales
callback (si json)
ca, es, en
lang
enc
utf-8, iso-8859-1

Parámetros generales
callback (si json)
ca, es, en
lang
enc
utf-8, iso-8859-1
incluso si json…

enc
utf-8, iso-8859-1
incluso si json…
(pero no php)

Una API es un proyecto en colaboración
enc
utf-8, iso-8859-1
incluso si json…
(pero no php)

Algunos parámetros comunes
id, i identificador

id, i identificador
http://api.idescat.cat/emex/v1/dades.xml?id=250019
Dame (la información de) el recurso 250019

id, i identificador
?
http://api.idescat.cat/emex/v2/municipios/250019.xml

id, i identificador
?
http://api.idescat.cat/emex/v2/comarcas/01.xml

id, i identificador
?
http://api.idescat.cat/emex/v2/geo/01.xml

id, i identificador
?
http://api.idescat.cat/emex/v2/geo/comarcas/01.xml

id, i identificador
?
http://api.idescat.cat/emex/v2/geo/comarcas/01.xml
+ amigable
+ fácil analítica
+ vocabulario

http://api.idescat.cat/onomastica-nombres/v1/dades...

http://api.idescat.cat/onomastica/nombres/v1/dades...

http://api.idescat.cat/onomastica/v1/nombres/dades...

?
http://api.idescat.cat/ono.../v1/nombres/xavier.xml

?
http://api.idescat.cat/ono.../v1/nombres/xavier.xml
http://api.idescat.cat/ono.../v1/apellidos/badosa.xml

http://api.idescat.cat/emex/v1/nodes.xml

http://api.idescat.cat/emex/v1/nodes.xml
?
http://api.idescat.cat/emex/v2/geo.xml
http://api.idescat.cat/emex/v2/geo/comarcas.xml

?
http://api.idescat.cat/pob/v2/geo.xml?q=abrera

v2, v1?
?
http://api.idescat.cat/pob/v2/geo.xml?q=abrera

http://api.idescat.cat/rect.../v1/categories.xml
http://api.idescat.cat/rect.../v1/categories.xml?id=tema

http://api.idescat.cat/rect.../v1/categories.xml?id=tema
?
http://api.idescat.cat/rect.../v1/categories/temes.xml

cadena abierta
q

posicio
paginación
http://api.idescat.cat/pob/v1/cerca.xml?q=a
&posicio=0

limit
posicio
paginación
(offset)
http://api.idescat.cat/pob/v1/cerca.xml?q=a
&posicio=0

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación
Dame los nodos
Dame los datos
Dame los resultados de la búsqueda
Damesugerencias
Damecategorías

API
Web
Puntos de acceso
Formatos
GET
Métodos
Autenticación
Dame los nodos
Dame los datos
Dame los resultados de la búsqueda
Damesugerencias
Damecategorías

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
Formatos
Tan abierto
como
el sitio web
Métodos
Autenticación

API
Web
Puntos de acceso
Formatos
Tan abierto
como
el sitio web
Métodos
Autenticación
↓ analítica

API
Web
Puntos de acceso
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
El Idescat se reserva el derecho de limitar las peticiones repetidas desde un mismo origen para garantizar el acceso al servicio para todo el mundo. Es responsabilidad del cliente emplear los mecanismos nece-sarios para evitar peticiones de la misma información en espacios de tiempo breve. El uso excesivo puede ocasionar la finaliza-ción del servicio. Si piensa hacer un uso intensivo de las APIs del Idescat póngase en contacto con el Idescat a fin de poder garantizar que este uso no perjudicará la disponibilidad general del servicio.
Formatos
Métodos
Autenticación

API
Web
Puntos de acceso
El Idescat se reserva el derecho de limitar las peticiones repetidas desde un mismo origen para garantizar el acceso al servicio para todo el mundo. Es responsabilidad del cliente emplear los mecanismos nece-sarios para evitar peticiones de la misma información en espacios de tiempo breve. El uso excesivo puede ocasionar la finaliza-ción del servicio. Si piensa hacer un uso intensivo de las APIs del Idescat póngase en contacto con el Idescat a fin de poder garantizar que este uso no perjudicará la disponibilidad general del servicio.
Formatos
Métodos
Autenticación
inespecíficas

1,2,3,4…
Infraestructura
cache
proxy
Interfaz
Homogeneización, simplificación,
gestión de errores…
Caché
Eficiencia
Estadísticas

Infraestructura
cache
proxy

Infraestructura
http://www.idescat.cat/api/
Documentación
cache
proxy

Infraestructura
Documentación
Galerías
Herramientas
cache
proxy

http://bitworking.org/news/193/Do-we-need-WADL

Infraestructura
Documentación
Galería
Herramientas
cache
proxy
Participación

Infraestructura
Documentación
Galería
Herramientas
cache
proxy
Participación
Condiciones de uso

G
R
A
C
I
A
S

International Solidarity Movement
North Carolina
Olancho Aid

http://xavierbadosa.com	2037
http://translate.googleusercontent.com	91
http://ultimate	41
http://twitter.com	13
http://abtasty.com	7
https://twitter.com	3
http://paper.li	2
https://abs.twimg.com	2

Anatomía de las APIs del Idescat

by Xavier Badosa

Accessibility

Categories

Upload Details

Usage Rights

8 Embeds 2,196

Statistics

Anatomía de las APIs del Idescat Presentation Transcript