Información general

La API Graph es la principal forma de ingresar datos en la plataforma de Facebook y extraerlos de esta. Se trata de una API basada en HTTP de nivel inferior que las aplicaciones pueden usar de manera programática para consultar datos, publicar nuevas historias, administrar anuncios, subir fotos y llevar a cabo una amplia gama de otras tareas.

Conceptos básicos

El nombre de la API Graph proviene del concepto de "gráfica social", es decir, una representación de la información en Facebook, que está compuesta por:

  • Nodos: básicamente objetos individuales, por ejemplo, un usuario, una foto, una página o un comentario.
  • Perímetros: conexiones entre una colección de objetos y un objeto único, por ejemplo, las fotos en una página o los comentarios en una foto.
  • Campos: datos sobre un objeto, por ejemplo, el cumpleaños de un usuario o el nombre de una página.

Normalmente, los nodos se usan para obtener datos sobre un objeto específico, los perímetros, para obtener colecciones de objetos a partir de un objeto único, y los campos, para obtener datos sobre un objeto único o todos los objetos en una colección.

HTTP

La API Graph está basada en HTTP, por lo que funciona con cualquier lenguaje que tenga una biblioteca HTTP, como cURL y urllib. Esto significa que la API Graph se puede usar directamente en el navegador. Por ejemplo, solicitar esta URL en el navegador…

https://graph.facebook.com/facebook/picture?redirect=false

... equivale a realizar esta solicitud cURL:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

Tokens de acceso

Tal vez te hayas percatado del parámetro access_token y el valor del marcador de posición en la solicitud cURL anterior. La mayoría de las solicitudes de la API Graph requieren un token de acceso. Con la documentación sobre tokens de acceso, entenderás poco a poco el funcionamiento de estos tokens, pero, por ahora, esto es todo lo que necesitas saber:

  • Casi todas las solicitudes de la API Graph requieren un token de acceso de algún tipo.
  • La manera más fácil de obtener tokens de acceso es mediante la implementación del inicio de sesión con Facebook.

En los ejemplos de solicitud y respuesta en pseudocódigo que se incluyen en la documentación sobre la API Graph no se hace referencia explícitamente a un token de acceso. Sin embargo, deberás suponer que se incluyó uno en la solicitud para que recibiera una respuesta.

Estructura

Este tema se trata de manera exhaustiva en nuestra Guía para usar la API Graph, pero estos son algunos conceptos generales:

  • Los nodos se usan para obtener datos sobre objetos individuales.
  • Los perímetros se usan para obtener colecciones de objetos conectados a un nodo o publicar objetos en dichas colecciones.
  • Los campos se usan para especificar los datos que se incluyen en las respuestas.

URL del host

Casi todas las solicitudes se pasan a la URL del host graph.facebook.com, salvo en el caso de las subidas de videos, que usan graph-video.facebook.com.

Identificadores de objeto

Para obtener información sobre un nodo, se debe consultar directamente su identificador, ya que son objetos individuales y dicho valor es único. Por ejemplo, la página de Facebook tiene el identificador 20531316728, que puedes usar para consultarla directamente.

GET graph.facebook.com
  /20531316728

Para obtener datos específicos (denominados "campos") sobre un nodo, incluye el parámetro fields y especifica los campos que se deberán devolver en la respuesta. En la referencia sobre el nodo "Page", se indica que uno de los campos que se pueden obtener al leer dicho objeto es el campo cover, que es la foto de portada de la página. La consulta se vería así:

GET graph.facebook.com
  /20531316728?fields=cover

La mayoría de los nodos tienen perímetros, que pueden devolver colecciones de objetos conectados al nodo en cuestión. Para consultar un perímetro, se usan su nombre y el identificador del nodo. La referencia sobre el nodo "Page" incluye el perímetro photos, que devuelve todos los objetos "Photo" que sean propiedad de la página. Por lo tanto, para obtener todas las fotos que sean propiedad de la página de Facebook, debes consultar el perímetro photos del nodo:

GET graph.facebook.com
  /20531316728/photos

En algunos nodos, se pueden actualizar los campos con operaciones POST. Por ejemplo, si eres administrador de la página de Facebook, puedes actualizar el campo description de esta manera:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

En algunos casos, los perímetros permiten publicar objetos nuevos en las colecciones de los nodos mediante operaciones POST. Este es un ejemplo que ilustra cómo publicar una foto en la respectiva colección de la página de Facebook:

POST graph.facebook.com
  /20531316728/photos

Por supuesto, para publicar un objeto en una colección, normalmente se requieren campos adicionales sobre dicho objeto, por ejemplo, una URL, un título o una descripción de la foto. En la documentación de referencia sobre los perímetros, se indican los campos obligatorios y opcionales.

Por último, generalmente es posible eliminar un nodo mediante una operación "DELETE" en el identificador del objeto:

DELETE graph.facebook.com
  /20531316728

Versiones

La API Graph tiene varias versiones. Encontrarás más información al respecto en la guía sobre versiones de la aplicación, pero aquí te explicaremos cómo hacer una llamada a una versión específica.

Realmente es sencillo: solo agrega la letra v seguida del número de la versión al principio de la ruta de acceso de la solicitud. Por ejemplo, esta es una llamada a la versión 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

Te recomendamos incluir el número de versión en las solicitudes, ya que, de lo contrario, usaremos de manera predeterminada la versión más antigua que esté disponible.

En el registro de cambios de la API Graph, se enumeran todas las versiones disponibles y, en la documentación de referencia, puedes filtrar el contenido para cada versión.

Próximos pasos

Ahora, veamos cómo usar la API Graph para conocer solicitudes más elaboradas y sus respuestas, así como las demás acciones que puedes realizar con ella.