Crear cuenta / - Bitacoras.comDesarrollo → Documentación ¬

Documentación de la API de Bitacoras.com

  1. Conceptos
    1. Peticiones HTTP
    2. Cabeceras HTTP
    3. Formato de los parámetros
    4. Parámetros básicos
    5. Formatos de salida
    6. Tipos de datos
    7. Elementos devueltos
    8. Codificación
    9. Límites
    10. Identificación y validación
  2. Métodos del API
    1. Anotacion
    2. Portada
    3. Hemeroteca
    4. Canales
    5. Buscar
    6. Geo
    7. Retweets
    8. Canal usuario
    9. Recomendaciones
    10. Descubrimientos
    11. Comentadas
    12. Sigue a
    13. Le siguen
    14. Comunidad
    15. Comentarios
    16. Usuario
    17. Usuarios
    18. Recibidos
    19. Inbox
    20. Top bitacoras
    21. Top usuarios

Conceptos básicos

Peticiones HTTP

Nuestra API soporta tanto peticiones GET como POST, y siempre han de enviarse indicando el método solicitado en los dos modos. Por ejemplo:

http://api.bitacoras.com/comentarios
http://api.bitacoras.com/portada

Formato de los parámetros

Los parámetros deben indicarse como pares parametro-valor, tanto en peticiones GET como POST (no se soportan peticiones con HTTP_RAW_POST_DATA).

Por ejemplo, una petición GET con varios parámetros:

http://api.bitacoras.com/canales/etiqueta/linux/format/xml

Y la misma petición POST:

POST /canales HTTP/1.1
Host: api.bitacoras.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 25
Connection: close

etiqueta=linux&format=xml

Cabeceras HTTP

Todas las peticiones realizadas, devolverán una cabecera HTTP adecuada

  • 200 OK: todo correcto
  • 400 Bad Request: error general, como bloqueo por mal uso (se indica en la descripción)
  • 401 Not Authorized: datos identificativos incorrectos (clave API o usuario/contraseña erróneos)
  • 404 Not Found: el método indicado no existe
  • 500 Internal Server Error: error inesperado, intentar más tarde

Parámetros básicos

Existen parámetros básicos, comunes para todas las peticiones:

  • key: clave API, obligatorio para todas las peticiones
  • user: nombre de usuario de Bitacoras.com
  • pass: contraseña de Bitacoras.com, codificada en MD5
  • limit: número de resultados por página
  • page: página de resultados
  • order: orden, sólo para anotaciones. Valores: fecha, votos
  • format: formato de salida de datos, por defecto JSON
  • operator: operador lógico (AND por defecto), sólo para anotaciones. Valores: OR, AND
  • encoding: codificación de salida, por defecto UTF-8

También existen parámetros especiales para los métodos que devuelven anotaciones:

  • order: campo de ordenación. Valores: fecha, votos
  • operator: operador lógico (AND por defecto). Valores: OR, AND

En caso de realizarse una petición en formato JSON puede indicarse el parámetro callback, una función o método al que se llamará por defecto pasándole el objeto JSON como parámetro. Esto permite integrar directamente una llamada GET en un código <script src="..."> sin necesidad de ningún otro lenguaje de programación o llamadas AJAX.

El formato de los parámetros debe ser el mismo que el del formato de salida con la única diferencia que al realizar una petición GET los valores de los paramétros deben estar codificados (RFC 1738). Esta codificación puede realizarse con la función urlencode() en PHP o encodeURIComponent() en JavaScript.

Un ejemplo al indicar la url http://www.ejemplo.com/?p=16:

http://api.bitacoras.com/comentarios/url/http%3A%2F%2Fwww.ejemplo.com%2F%3Fp%3D16/

Su equivalente POST sería:

POST /comentarios HTTP/1.1
Host: api.bitacoras.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 44
Connection: close

url=http%3A%2F%2Fwww.ejemplo.com%2F%3Fp%3D16

Formatos de salida

Los datos se pueden devolver en diferentes formatos: JSON (formato por defecto), XML, php o los formatos de sindicación RSS y Atom (estos dos últimos sólo en el caso de los métodos de lectura de anotaciones). Para obtener los datos en el formato deseado, basta con indicarlo con el parámetro format.

Exceptuando los formatos de sindicación (RSS y Atom), en el resto de formatos, siempre hay los siguientes elementos comunes:

  • status: resultado de la peticion, pudiendo ser success o error
  • items: número total de resultados (por ejemplo, anotaciones en un canal)
  • message: mensaje descriptivo del resultado de la petición
  • status: los datos en si

Por ejemplo, una petición correcta en PHP, tras hacer un var_dump() del resultado:

stdClass Object
(
    [status] => success
    [items] => 1
    [message] => La petición se ha procesado correctamente
    [data] => Array
        (
            [0] => stdClass Object
                (
                    [autor] => David Martinez Arcos
                    [alias] => dmnet
                    [texto] => Muy interesante :)
                    [fecha] => 1236613115
                    [class_methods] => Array
                        (
                        )
                )
        )
)

Otro ejemplo: el resultado de una petición errónea en XML sería:

<?xml version="1.0" encoding="UTF-8"?>
<request>
	<status>error</status>
	<items>0</items>
	<message>Es imprescindible indicar una clave</message>
	<data></data>
</request>

Tipos de datos devueltos

Éstos son los formatos de los tipos de datos que se devuelven:

  • Fechas: formato Unix Timestamp
  • URLs: sin codificar y siempre con http://
  • Números: enteros o flotantes para JSON/serialize o como texto sin separación de miles para XML

Cualquier otro dato se devuelve como una cadena de texto.

Elementos devueltos

Los datos se devueven en listas (o matrices) predefinidas:

  • Anotaciones:
    • autor: nombre completo del autor
    • alias: alias en Bitacoras.com del autor
    • avatar: imagen del usuario (32x32px)
    • fecha: fecha de publicación
    • votos: número de votos
    • url: dirección completa de la anotación
    • bitacora: dirección completa de la bitácora
    • nombre: nombre completo de la bitácora
    • titulo: título completo
    • contenido: resumen del contenido sin etiquetas HTML
  • Tweets:
    • id: identificador (status)
    • alias: alias en Twitter.com del autor
    • avatar: imagen del usuario
    • fecha: fecha de publicación
    • url: dirección completa del tweet
    • contenido: texto del tweet
  • Usuarios:
    • alias: alias en Bitacoras.com
    • avatar: imagen del usuario (32x32px)
    • descripcion: pequeña descripción
    • nombre: nombre completo
    • pais: pais, si se ha indicado
    • ciudad: ciudad, si se ha indicado
  • Actividad:
    • url: URL de la actividad: anotacion, usuario...
    • tipo: tipo de actividad (anotacion, voto, comentario...)
    • alias: alias en Bitacoras.com del autor
    • avatar: imagen del usuario (32x32px)
    • fecha: fecha de publicación
    • texto: texto descriptivo, con etiquetas HTML
  • Mensajes y comentarios:
    • autor: nombre completo del autor
    • alias: alias en Bitacoras.com del autor
    • avatar: imagen del usuario (32x32px)
    • fecha: fecha de publicación
    • texto: contenido filtrado, con etiquetas HTML
  • Valor: valor tal cual (cadena de texto, entero, flotante...)

Codificación

Por defecto, se devuelven los datos en UTF-8, aunque es posible especificar otra codificación (ISO-8859-1 o Windows-1252) mediante el parámetro encoding.

Límites

De momento no se establecen límites en el número de peticiones (pueden establecerse en un futuro o dependiendo de la carga del sistema) pero sí se establecen límites para la paginación y el número de resultados: no podrán superarse los 100 elementos (especificados por el parámetro limit) ni se podrán superar los 1500 elementos en paginación (especificados por la combinación de los parámetros limit y page).

Identificación y validación

La identificación del cliente se realiza gracias al parámetro key, que debe indicarse obligatoriamente en todas las peticiones. Complementariamente, para los métodos que lo requieran, deberán indicarse los parámetros user y pass para poder acceder a los datos privados. Estos dos parámetros sólo se pueden enviar por método POST. También es posible enviar estos parámetros con una autentificación HTTP Authorization Basic. Generalmente los métodos que requerirán la validación seran todos aquellos que accedan a datos vinculados exclusivamente a usuarios, como listas de seguidores, recomendaciones o descubrimientos. Siempre que se solicite la contraseña de acceso, deberá estar codificada con MD5, para así no transferirla en texto plano.

Métodos

A continuación se describen los métodos disponibles.

anotacion

Devuelve la anotacion indicada por la URL. Es util para saber si la anotacion ha sido indexada por Bitacoras.com.

  • URL: http://api.bitacoras.com/anotacion
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml, rss, atom
  • Parámetros (1):
    1. url: cadena, URL completa de la anotacion codificada con urlencode()
  • Devuelve: anotaciones

portada

Devuelve las anotaciones actualmente en portada

hemeroteca

Devuelve las anotaciones que llegaron a portada el dia indicado

  • URL: http://api.bitacoras.com/hemeroteca
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml, rss, atom
  • Parámetros (1):
    1. fecha: cadena, Fecha en formato YYYY-MM-DD: 2009-09-01
  • Devuelve: anotaciones

canales

Devuelve las anotaciones de un canal

  • URL: http://api.bitacoras.com/canales
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml, rss, atom
  • Parámetros (1):
    1. etiqueta: cadena, Tag, etiqueta, termino de busqueda codificado con urlencode()
  • Devuelve: anotaciones

buscar

Devuelve las anotaciones de una busqueda

  • URL: http://api.bitacoras.com/buscar
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml, rss, atom
  • Parámetros (2):
    1. busqueda: cadena, Terminos de busqueda o una URL codificada con urlencode()
    2. ciudad: cadena (opcional), Indica si también ha de buscarse en el campo ciudad
  • Devuelve: anotaciones

geo

Devuelve las anotaciones de una busqueda GEO

retweets

Devuelve los retweets realizados a una anotacion

  • URL: http://api.bitacoras.com/retweets
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (1):
    1. url: cadena, URL completa de la anotacion codificada con urlencode()
  • Devuelve: tweets

canal_usuario

Devuelve las anotaciones escritas por un usuario

recomendaciones

Devuelve las ultimas recomendaciones del usuario indicado

descubrimientos

Devuelve los ultimos descubrimientos del usuario indicado

comentadas

Devuelve las ultimas anotaciones en las que el usuario ha comentado. No confundir con comentarios, ya que ese metodo devuelve los ultimos comentarios y no las anotaciones.

sigue_a

Devuelve la lista de usuarios a los que sigue un usuario

  • URL: http://api.bitacoras.com/sigue_a
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (2):
    1. alias: cadena, Alias del usuario
    2. imagen: true/false (opcional), Incluir unicamente los que tengan avatar
  • Devuelve: usuarios

le_siguen

Devuelve la lista de seguidores de un usuario

  • URL: http://api.bitacoras.com/le_siguen
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (2):
    1. alias: cadena, Alias del usuario
    2. imagen: true/false (opcional), Incluir unicamente los que tengan avatar
  • Devuelve: usuarios

comunidad

Devuelve la actividad de la comunidad de un usuario

  • URL: http://api.bitacoras.com/comunidad
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (1):
    1. alias: cadena, Alias del usuario
  • Devuelve: usuarios

comentarios

Devuelve los comentarios realizados en una anotacion

  • URL: http://api.bitacoras.com/comentarios
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (1):
    1. url: cadena, URL completa de la anotacion codificada con urlencode()
  • Devuelve: mensajes

usuario

Lee los datos de un usuario identificado por su alias en Bitacoras.com

  • URL: http://api.bitacoras.com/usuario
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (1):
    1. alias: cadena, alias en Bitacoras.com
  • Devuelve: usuarios

usuarios

Busca usuarios en base a su nombre y apellidos

  • URL: http://api.bitacoras.com/usuarios
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (2):
    1. nombre: cadena, nombre
    2. apellidos: cadena (opcional), apellidos
  • Devuelve: usuarios

recibidos

Devuelve los ultimos mensajes recibidos en la bandeja de entrada

inbox

Devuelve el numero de mensajes en la bandeja de entrada

top_bitacoras

Devuelve la posición de una bitácora en el TOP Bitacoras

  • URL: http://api.bitacoras.com/top_bitacoras
  • Identificación: clave únicamente
  • Formatos: json, serialize, xml
  • Parámetros (2):
    1. bitacora: cadena, Direccion completa de la bitacora codificada con urlencode()
    2. pais: cadena (opcional), ISO del pais (2 caracteres)
  • Devuelve: valor
  • Información extra:

top_usuarios

Devuelve la posición de un usuario en el TOP Usuarios