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.