Información general sobre la API Graph

La API Graph es el modo principal para extraer e ingresar datos en la plataforma de Facebook. Se trata de una API basada en HTTP de nivel inferior que puedes utilizar de manera programática para consultar datos, publicar nuevas historias, administrar anuncios, subir fotos y llevar a cabo varias tareas más propias de una aplicación.

Conceptos básicos

La API Graph se llama así por la idea de una "gráfica social", una representación de la información en Facebook que consta de:

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

La API Graph está basada en HTTP, por lo que funciona con cualquier lenguaje que tenga una biblioteca HTTP, como cURL y urllib. Explicaremos un poco más sobre lo que puedes hacer en la sección que hay a continuación, pero significa que también puedes utilizar la API Graph directamente en tu navegador, por ejemplo, una solicitud de la API Graph es equivalente a:

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

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

Esta información general te mostrará cómo la API Graph puede leer y publicar datos en la gráfica social.

Cómo se estructura

En nuestra Guía sobre el uso de la API Graph tratamos esto de forma exhaustiva, pero en general puedes leer las API haciendo solicitudes GET HTTP a los nodos o perímetros en esos nodos.

Casi todas las solicitudes se pasan a la API en graph.facebook.com; la única excepción son las subidas de video que utilizan graph-video.facebook.com.

Identificadores de objeto

Cada nodo tiene un identificador único que se utiliza para acceder a este mediante la API Graph. No documentamos específicamente la estructura o el formato de ningún nodo o identificador de objeto porque es extremadamente probable que cambie con el tiempo y las aplicaciones no deben hacer suposiciones con base en la estructura actual.

Aquí te explicamos cómo utilizar el identificador para hacer una solicitud para un nodo:

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

O perímetro:

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

Por lo general puedes publicar en las API mediante solicitudes POST HTTP con parámetros en el nodo:

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

O perímetro:

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

La eliminación mediante las API se lleva a cabo con las solicitudes DELETE HTTP (y la actualización mediante solicitudes POST) en los mismos extremos.

Versiones de API

La API Graph tiene varias versiones disponibles a las que se puede acceder en cualquier momento. Cada versión contiene un conjunto de campos básicos y operaciones perimetrales. Garantizamos que esas API básicas estarán disponibles y sin modificar en esa versión durante al menos dos años a partir de su lanzamiento. El registro de cambios de la plataforma te puede indicar qué versiones están disponibles actualmente.

Determinadas operaciones, como la publicación dentro un perímetro, o determinados campos dentro de un nodo pueden ser básicos sin que todo el perímetro o nodo sea básico. Indicamos estas API básicas mediante el símbolo en nuestra documentación de referencia de la API Graph.

Las API fuera de estas API básicas se conocen como API extendidas. Todavía se accede a estas API a través de rutas con versiones, pero potencialmente se pueden modificar o eliminar en cualquier momento, sujetas a migraciones de 90 días que se anunciarían en el plan de nuestra plataforma. Alternativamente, se pueden incluir simplemente en la siguiente versión de API disponible.

Puedes leer más sobre el objetivo del control de versiones en nuestra guía, pero aquí te explicaremos cómo hacer una llamada a una versión específica de la API Graph.

Realmente es sencillo: solo agrega el identificador de la versión al principio para iniciar la ruta de acceso de la solicitud. Por ejemplo, esta es una llamada a v2.2:

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

Funciona para todas las versiones, en este formato general:

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

Donde X.Y es la versión necesaria. Publicamos una lista completa de las versiones disponibles en nuestro registro de cambios. En toda nuestra documentación de referencia de la API Graph, se ofrece información por versión, así que comprueba que estás mirando la versión correcta, ya que algunas versiones quitan nodos y perímetros o algunas versiones agregarán nodos y perímetros.

Ahora vamos a probar una solicitud de API para que puedas ver lo fácil que es.

Cargar el explorador de la API Graph

La manera más fácil de entender la API Graph es utilizarla con el explorador de la API Graph, una herramienta de bajo nivel que puedes utilizar para consultar, agregar y eliminar datos. Es un recurso muy práctico para tener a tu alcance cuando haces la integración con Facebook. Así es que tu siguiente paso es ir al explorador de la API Graph.

Explorador de la API Graph

Generar un token de acceso de usuario básico

Cuando empieces a crear tu propia aplicación, necesitarás obtener información sobre los tokens de acceso y cómo generarlos con el inicio de sesión con Facebook, pero por ahora, podemos obtener uno de forma realmente rápida a través del explorador de la API Graph:

  1. Haz clic en el botón Get Token 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; solo haz clic en el botón azul Get Access Token.
  4. Verás un cuadro de diálogo de inicio de sesión con Facebook. Haz clic en OK para continuar.

Hacer tu primera solicitud

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

Ahora presiona el botón "Submit". Tardará unos segundos en procesarse, pero ahora debes ver todo un conjunto de información aparecer en el panel de respuesta. Lo que aparece aquí para ti está determinado por la configuración de privacidad de tu perfil, pero debe haber al menos algunos campos básicos:

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

GET graph.facebook.com
  /me

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

Felicitaciones, ¡acabas de hacer tu primera solicitud de la API Graph!

Obtener permisos de publicación

A continuación, vamos a intentar publicar algo en Facebook con la API Graph. Harás esto en tu aplicación solo si estás creando tu propio editor de publicaciones personalizado y no estás utilizando uno de los cuadros de diálogo de contenido compartido en la web, iOS o Android. Los cuadros de diálogo de contenido compartido de Facebook no necesitan que implementes el inicio de sesión con Facebook o que crees tu propia interfaz para permitir que las personas compartan.

Para explorar la publicación con la API Graph, vuelve a hacer clic en el botón "Obtener token de acceso" y, esta vez, elige el permiso publish_actions:

Ahora haz clic en el botón azul "Obtener token de acceso" y volverás a ver el cuadro de diálogo de inicio de sesión. Aquí se te pedirá permiso para que el explorador de la API Graph publique en tu nombre. Si quieres, puedes cambiar el público aquí a "Solo yo" para que solo tú puedas ver la publicación, pero debes aceptar este cuadro de diálogo y pasar al siguiente paso.

Hacer una publicación

Si pediste el permiso publish_actions, ahora haz clic en el botón que dice "GET" y elige "POST" en el selector desplegable que aparece. Ingresa me/feed en el campo de la ruta de acceso y después haz clic en "Add a Field".

En los nuevos campos que aparecen, pon message como el "nombre" y Hello, World como el "valor". Debe tener el siguiente aspecto:

Ahora haz clic en el botón azul "Submit" y, después de unos segundos, el panel de respuesta mostrará algo como esto:

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

Esto significa que acabas de publicar por primera vez a través de la API Graph. Puedes ir a tu perfil y deberías poder ver la publicación ahí:

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

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

Próximos pasos

Ya conociste los conceptos básicos aquí. ¿Por qué no sigues aprendiendo más sobre el uso de la API Graph? Si todavía no lo hiciste, te recomendamos que primero leas sobre el inicio de sesión con Facebook y, especialmente, sobre cómo generar tokens de acceso, ya que los necesitarás para hacer solicitudes de la API Graph más complejas.