Información general sobre la API Graph

La API Graph es la principal vía para introducir datos en la plataforma de Facebook y extraer información de esta. Es una API de bajo nivel basada en HTTP que permite consultar datos, publicar historias nuevas, administrar anuncios, subir fotos y realizar varias tareas adicionales mediante programación que puede implementar una aplicación.

Aspectos básicos

La API Graph recibe su nombre de la idea de "gráfica social", una representación de la información disponible en Facebook, que comprende los elementos siguientes:

  • Nodos: básicamente "objetos", como un usuario, una foto, una página o un comentario.
  • Perímetros: las conexiones entre esos "objetos", como las fotos de una página o los comentarios de una foto.
  • Campos: información sobre esos "objetos", como el cumpleaños de una persona o el nombre de una página.

La API Graph se basa en HTTP, por lo que es compatible con cualquier lenguaje que cuente con una biblioteca HTTP, como cURL y urllib. Aunque explicaremos de forma más detallada qué puedes hacer con la API en la siguiente sección, esto significa que puedes utilizarla directamente en tu navegador. Por ejemplo, una solicitud de la API Graph equivale a:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

La mayoría de las solicitudes de la API Graph requieren el uso de identificadores de acceso, que tu aplicación puede generar implementando el inicio de sesión con Facebook.

En esta información general se describe cómo la API Graph puede leer y publicar datos en la gráfica social.

Cómo se estructura la API Graph

Aunque tratamos este tema íntegramente en la guía Uso de la API Graph, en términos generales, se pueden leer las API realizando solicitudes HTTP GET a nodos o a perímetros de estos nodos.

Prácticamente todas las solicitudes se pasan a la API en graph.facebook.com. La única excepción son las cargas de vídeos, que utilizan graph-video.facebook.com.

Identificadores de objeto

Cada nodo tiene un identificador único que se utiliza para acceder a él a través de la API Graph. No documentamos ninguna estructura o formato de nodo-identificador de objeto precisamente porque es muy probable que cambien con el tiempo, y las aplicaciones no deberían hacer suposiciones basándose en la estructura actual.

A continuación se muestra cómo se utilizaría el identificador para realizar una solicitud de un nodo:

GET graph.facebook.com
  /{node-id}

También puedes realizar este tipo de solicitud con un perímetro:

GET graph.facebook.com
  /{node-id}/{edge-name}

En líneas generales, puedes publicar en las API realizando solicitudes HTTP POST con parámetros al nodo:

POST graph.facebook.com
  /{node-id}

También puedes realizar este tipo de solicitud con un perímetro:

POST graph.facebook.com
  /{node-id}/{edge-name}

Para eliminar elementos mediante las API, se realizan solicitudes HTTP DELETE a los mismos extremos (para actualizar, se realizan solicitudes POST).

Versiones de la API

La API Graph tiene varias versiones disponibles en cualquier momento. Cada versión contiene un conjunto de campos y operaciones de perímetro principales. Garantizamos que estas API principales estarán disponibles y no se modificarán en la versión correspondiente durante al menos dos años a partir de su lanzamiento. Puedes consultar las versiones disponibles en el registro de cambios de la plataforma.

Determinadas operaciones, como la publicación dentro de un perímetro o determinados campos de un nodo, pueden ser principales sin necesidad de que lo sea todo el perímetro o todo el nodo. Indicamos cuáles son las API básicas mediante el símbolo en nuestra documentación de referencia de la API Graph.

A las API que no son principales se las denomina ampliadas. Estas API siguen estando accesibles a través de rutas con versión, pero pueden modificarse o eliminarse en cualquier momento en función de las migraciones de 90 días que se anunciarían en nuestro calendario para la plataforma. También pueden incluirse en la siguiente versión disponible de la API.

Aunque puedes obtener más información sobre las versiones previstas en nuestra guía, aquí te explicamos cómo realizar una llamada a una versión concreta de la API Graph.

Es muy sencillo: basta con añadir el identificador de la versión al inicio de la ruta de la solicitud. Por ejemplo, esta es una llamada a la v2.2:

GET graph.facebook.com
  /v2.2/me

Funciona con todas las versiones, con este formato general:

GET graph.facebook.com
  /vX.Y/{request-path}

El elemento X.Y es la versión necesaria. Publicamos la lista completa de versiones disponibles en nuestro registro de cambios. Toda nuestra documentación de referencia sobre la API Graph proporciona información específica de cada versión, por lo que asegúrate de consultar la versión correcta. Algunas versiones añaden nodos y perímetros, mientras que otras los eliminan.

A continuación te explicaremos cómo realizar una solicitud a la API, para que veas lo sencillo que es.

Cargar el explorador de la API Graph

La forma más sencilla de conocer el funcionamiento de la API Graph es utilizarla con su explorador, una herramienta de bajo nivel que permite consultar, añadir y eliminar datos. Se trata de un recurso muy práctico durante la integración de las aplicaciones con Facebook. Por lo tanto, el siguiente paso es acceder al explorador de la API Graph.

Explorador de la API Graph

Generar un identificador de acceso de usuario básico

Cuando te dispongas a desarrollar tu propia aplicación, tendrás que obtener información sobre los identificadores de acceso y cómo generarlos utilizando el inicio de sesión con Facebook, pero, por ahora, podemos obtener uno rápidamente con el explorador de la API Graph:

  1. Haz clic en el botón Get Token situado en la parte superior derecha del explorador.
  2. Elige la opción Get User Access Token.
  3. En el siguiente cuadro de diálogo, no marques ninguna casilla. Simplemente haz clic en el botón Get Access Token de color azul.
  4. Verás un cuadro de diálogo de inicio de sesión con Facebook. Haz clic en OK para continuar.

Realizar tu primera solicitud

Ya estás listo para realizar tu primera solicitud de la API Graph. Empezaremos por la solicitud "read". En el campo de texto situado junto al botón desplegable "GET" (lo denominaremos "campo de ruta"), elimina el texto existente y escribe "me":

A continuación, pulsa el botón "Enviar". Al cabo de unos segundos, aparecerá una gran cantidad de información en el panel de respuesta. Aunque lo que se muestra en este panel dependerá de la configuración de privacidad de tu perfil, deberían aparecer al menos algunos campos básicos:

Lo que acabas de hacer en el explorador de la API Graph es el equivalente a la solicitud "read" siguiente de la API:

GET graph.facebook.com
  /me

/me es un extremo especial que se traduce en el identificador de usuario de la persona cuyo identificador de acceso se utiliza para realizar la solicitud.

Enhorabuena. Acabas de realizar tu primera solicitud de la API Graph.

Obtener permisos de publicación

Ahora te explicaremos cómo realizar publicaciones en Facebook con la API Graph. Esta acción solo la llevarías a cabo en tu aplicación si fueses a desarrollar tu propio editor personalizado y no utilizaras uno de los cuadros de diálogo de contenido compartido para web, iOS o Android. Los cuadros de diálogo de contenido compartido de Facebook no te obligan a implementar el inicio de sesión con Facebook ni a desarrollar tu propia interfaz para que la gente pueda compartir.

Para publicar con la API Graph, haz clic de nuevo en el botón "Obtener identificador de acceso" y, esta vez, elige el permiso publish_actions:

A continuación, haz clic en el botón "Obtener identificador de acceso" de color azul para que aparezca de nuevo el cuadro de diálogo de inicio de sesión. En este cuadro, se te solicitará permiso para que el explorador de la API Graph publique en tu nombre. Si quieres ser el único que puede ver la publicación, cambia el público a "Solo yo" desde aquí, acepta en el cuadro de diálogo y ve al siguiente paso.

Realizar una publicación

Si has solicitado el permiso publish_actions, haz clic en el botón "GET" y elige "POST" en el selector desplegable que aparece. Escribe me/feed en el campo de ruta y haz clic en "Añadir un campo".

En los nuevos campos que aparecen, especifica message para "name" y Hello, World para "value". El resultado debería ser similar a esto:

Ahora, haz clic en el botón "Enviar" de color azul. Transcurridos unos segundos, el panel de respuesta debería mostrar algo parecido a lo siguiente:

{
  "id": "{new-post-id}"
}

Esto significa que has realizado tu primera publicación mediante la API Graph. Si vas a tu perfil, podrás ver la publicación allí:

Lo que acabas de hacer en el explorador de la API Graph es el equivalente a la solicitud "publish" siguiente de la API:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

Siguientes pasos

Aquí hemos abordado únicamente los aspectos básicos. ¿Quieres obtener más información sobre el uso de la API Graph? Si no lo has hecho aún, te recomendamos que leas primero la documentación sobre el inicio de sesión con Facebook y, especialmente, sobre cómo generar identificadores de acceso que necesitarás para realizar solicitudes de la API Graph más complejas.