Conceptos básicos del protocolo de las API de datos de Google

En este documento se describen los aspectos básicos del protocolo que utilizan las API de datos de Google. Se incluyen ejemplos de cómo se ven una consulta y los resultados, entre otros.

Si deseas obtener más información sobre las API de datos de Google, consulta el documento de la Guía para programadores de datos de Google y la Guía de referencia.

Público

Este documento está destinado a cualquier persona que desee comprender la idea general del protocolo y el formato XML que utilizan las API de datos de Google.

Incluso si solo quieres escribir código que use las bibliotecas cliente específicas del lenguaje, te recomendamos que leas este documento para comprender lo que sucede debajo de la capa de abstracción de biblioteca cliente.

En este documento, se asume que comprende los conceptos básicos de XML, los espacios de nombres, los feeds sindicados y las solicitudes GET, POST, PUT y DELETE en HTTP, así como el concepto de "recurso" de HTTP. Para obtener más información sobre estos temas, consulta la sección Recursos adicionales de este documento.

Este documento no depende de ningún lenguaje de programación en particular. Tu cliente puede interactuar con el servidor mediante cualquier lenguaje de programación que te permita emitir solicitudes HTTP y analizar respuestas basadas en XML.

Ejemplos

En los siguientes ejemplos, se muestran las solicitudes al protocolo de la API de datos que se pueden enviar a un servicio genérico y los resultados que puedes recibir. Para ver ejemplos de cómo enviar las solicitudes mediante varios lenguajes de programación, consulta las muestras específicas del lenguaje y las bibliotecas cliente. Para obtener información sobre el uso de las API de datos de Google con servicios específicos de Google, consulta la documentación específica del servicio.

Cómo solicitar un feed u otro recurso

Supongamos que hay un feed llamado /myFeed y que suponemos que, por el momento, no contiene ninguna entrada. Para verla, envía la siguiente solicitud al servidor:

GET /myFeed

El servidor responde:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

Ten en cuenta que, si bien el feed no contiene entradas, sí contiene metadatos, como un título y el nombre de un autor.

Cómo insertar una entrada nueva

Para crear una entrada nueva, envía una solicitud POST y proporciona la representación XML de la entrada nueva:

POST /myFeed

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

Ten en cuenta que no proporcionas los elementos Atom <id>, <link> o <updated> estándar; el servidor los crea en respuesta a tu solicitud POST. También ten en cuenta que el autor de un feed no tiene que ser el mismo que el de una entrada.

El servidor responde:

201 CREATED

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

Busca una string

Para realizar una búsqueda en el texto completo de una string en particular, cuando uses un servicio que admita búsquedas en el texto completo, envía una solicitud GET con el parámetro q. Para obtener más información acerca de los parámetros de consulta, visita Solicitudes de consulta en el documento de referencia del protocolo.

GET /myFeed?q=This

El servidor responde con todas las entradas que coinciden con la string de búsqueda This. (en este caso, solo hay uno).

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/1/"/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my entry</content>
  </entry>
</feed>

Actualiza una entrada

Para actualizar una entrada existente, usa PUT, con el URI de edición de la entrada (como lo proporciona el servidor en el ejemplo anterior, en el elemento <link rel="edit">).

Si tu firewall no permite PUT, realiza una POST HTTP y configura el encabezado de anulación del método de la siguiente manera:

X-HTTP-Method-Override: PUT

En el siguiente ejemplo, cambiamos el texto de su entrada anterior (por ejemplo, "This is my entry") a un valor nuevo ("This is my first entry").

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

El servidor responde:

200 OK

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

Ten en cuenta que el URI de edición ha cambiado; termina con "/2/" en lugar de "/1/". El número final en el URI de edición es un número de versión. Para obtener más información sobre las versiones, consulta la sección Simultaneidad optimista del documento de referencia del protocolo.

Para ver la entrada nueva en contexto, vuelve a solicitar el recurso completo:

GET /myFeed

El servidor responde:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my first entry.</content>
  </entry>
</feed>

Borra una entrada

Para borrar una entrada existente, envía una solicitud DELETE con el URI de edición de la entrada (como lo proporcionó el servidor en el ejemplo anterior).

Si tu firewall no permite DELETE, realiza una POST HTTP y configura el encabezado de anulación del método de la siguiente manera:

 X-HTTP-Method-Override: DELETE

En el siguiente ejemplo, se borra una entrada:

DELETE /myFeed/1/2/

El servidor responde:

200 OK

Haz otra GET para ver que el feed ahora no contiene entradas:

GET /myFeed

El servidor responde:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

Si la eliminación falla, el servidor responde con un código de error. Para obtener más información, consulta los códigos de estado HTTP en el documento de referencia del protocolo.

Recursos adicionales

Los siguientes documentos de terceros pueden resultarte útiles:

Volver al principio