Conceptos básicos del protocolo

Advertencia: Esta página trata sobre las API anteriores de Google, las API de datos de Google, y solo es relevante para las API que aparecen en el directorio de las API de datos de Google, muchas de las cuales se reemplazaron con API más nuevas. Para obtener información sobre una API nueva específica, consulta la documentación de la API nueva. Para obtener información sobre cómo autorizar solicitudes con una API más reciente, consulta Autenticación y autorización de cuentas de Google.

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

Para obtener más información acerca del Protocolo de datos de Google, consulte la página de descripción general de la Guía para programadores y la Referencia de protocolo.

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.

Si deseas probar los ejemplos de este documento sin escribir ningún código, tal vez te resulten útiles las utilidades de línea de comandos cURL o Wget. Para obtener más información, consulta las páginas manuales de esas utilidades o el documento Cómo usar cURL para interactuar con servicios que usan el protocolo de datos de Google.

Ejemplos

En los siguientes ejemplos, se muestran las solicitudes HTTP que puedes enviar a un servicio genérico mediante el protocolo de la API del protocolo de datos de Google directamente y los resultados que podrías 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 del protocolo de datos de Google con servicios específicos de Google, consulte 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 HTTP al servidor:

GET /myFeed

El servidor responde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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. También contiene un identificador de versión, con el formato de una ETag HTTP.

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' encoding='utf-8'?>
<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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <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 un feed que contiene todas las entradas que coinciden con la string de búsqueda This. (en este caso, solo hay uno).

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <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 gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/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, debes realizar los siguientes pasos.

  1. Recupera la entrada que deseas actualizar.
  2. Modifícalo como desees.
  3. Envía una solicitud PUT, con la entrada actualizada en el cuerpo del mensaje, al URI de edición de la entrada. El URI de edición aparece en el ejemplo anterior como el atributo href del elemento <link rel='edit'>.

También debes especificar la ETag de la entrada original para asegurarte de no sobrescribir los cambios de otra persona.

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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/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>

Ten en cuenta que la ETag cambió. Para obtener más información sobre las versiones de los recursos, consulta la sección Control de versiones de recursos (ETags) 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' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <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 gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/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>
</feed>

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

X-HTTP-Method-Override: PUT

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

Cuando borras una entrada, puedes optar por hacer una eliminación condicional (solo borrar si la entrada no cambió desde la última vez que la recuperaste) o una eliminación incondicional. Para obtener más información, consulta la sección Control de versiones de recursos (ETags) del documento de referencia del protocolo. Para hacer una eliminación incondicional, configura el siguiente encabezado HTTP:

If-Match: *

En el siguiente ejemplo, se borra una entrada (si los encabezados están configurados correctamente):

DELETE /myFeed/1/

El servidor responde:

200 OK

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

GET /myFeed

El servidor responde con un feed que no contiene más que metadatos:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <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.

Cómo solicitar entradas o feeds parciales (Experimental)

A diferencia del feed de ejemplo simple que se muestra en este documento, los feeds pueden ser bastante complejos en la práctica. Con algunas API, puedes solicitar solo los elementos o atributos de interés, en lugar de la representación de recursos completa. Cuando evitas recuperar y analizar datos innecesarios, puedes mejorar considerablemente la eficiencia de tu aplicación cliente.

Para solicitar una respuesta parcial, usa el parámetro de consulta fields a fin de especificar qué elementos o atributos deseas que se muestren. Para obtener más información, consulta Respuesta parcial en el documento de referencia del protocolo.

En el siguiente ejemplo, solo se solicita el ID del feed, además del autor y el título de cada entrada de feed.

GET /myFeed?fields=id,entry(author)

El servidor responde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Puedes usar el parámetro fields con cualquier tipo de solicitud que muestre datos. Además de GET, incluye POST y PUT (así como PATCH, que se usa para realizar solicitudes de actualización parcial).

Nota: El parámetro de consulta fields solo controla los datos que se envían en respuesta a una solicitud; no afecta los datos que debes proporcionar en el cuerpo de una solicitud PUT, POST o PATCH.

A continuación, se muestran ejemplos de POST y PUT.

  • Cuando realizas una solicitud POST para una respuesta parcial, debes proporcionar los mismos datos que se describen en Inserta una entrada nueva. En el siguiente ejemplo, se solicita una respuesta parcial que solo contiene el título de la entrada recién creada: 
    POST /myFeed?fields=title
      
...data...

    El servidor responde:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Cuando realizas una solicitud PUT para una respuesta parcial, debes proporcionar una versión modificada de la representación completa del recurso, como se describe en Actualiza una entrada. En el siguiente ejemplo, se solicita una respuesta parcial que contiene solo el valor de ETag nuevo de la entrada modificada: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...
    .

    El servidor responde:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Actualiza campos específicos (experimental)

Si la API que usas admite respuestas parciales y tiene campos que se pueden editar, también puedes evitar el envío de datos innecesarios cuando modificas una entrada. La actualización parcial te permite enviar datos solo para los campos que deseas cambiar.

Para usar una actualización parcial, envía una solicitud PATCH al mismo URI de edición que usas con PUT. Los datos que envíes con PATCH deben seguir ciertas convenciones. Sin embargo, la semántica es lo suficientemente flexible para que reemplaces datos en el recurso de destino, lo agregues o incluso lo borres, todo con una sola solicitud.

Nota: Al igual que con PUT, debes especificar la ETag de la entrada original para asegurarte de no sobrescribir los cambios de otra persona.

Para obtener más información sobre PATCH y su semántica, consulta Actualización parcial en el documento de referencia del protocolo.

En este ejemplo, se muestra una solicitud de actualización parcial que modifica el título de la entrada:

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

Cuando el servidor recibe una solicitud PATCH, primero quita los campos especificados por el atributo gd:fields de la entrada (si está presente); luego, combina los datos proporcionados en el cuerpo de la solicitud con el recurso de destino. En este ejemplo, el elemento title se quita primero del recurso de destino y, luego, se combina el nuevo valor del título. Efectivamente, esta solicitud reemplaza el título anterior por el nuevo.

Sin embargo, ten en cuenta que la semántica de PATCH es fusionar la representación parcial en el recurso existente. No siempre es necesario quitar un campo para actualizar su valor.

  • Si el campo solo puede existir una vez en la entrada objetivo, cuando se realice una combinación, el campo de la representación parcial reemplazará el campo correspondiente en la entrada objetivo.
  • Si el campo puede existir más de una vez en la entrada objetivo, cuando se realice la combinación, el campo parcial se agregará a la entrada objetivo.

La diferencia entre la combinación de campos repetidos y no repetidos se muestra en el siguiente ejemplo, en el que se agrega un nuevo título y autor a la entrada sin usar el atributo gd:fields para quitar uno de ellos primero.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Dado que la representación de entrada parcial no tiene atributo gd:fields, no se quita ningún campo. Sin embargo, los valores nuevos para los elementos <title> y <author> se combinan con el recurso de destino:

  • Dado que Atom solo permite un título por entrada, el título nuevo reemplaza el valor existente. 
  • Dado que Atom permite la inclusión de varios autores por entrada, el autor nuevo se anexa a la lista de elementos de autor que ya se encuentran en el recurso de destino.

    Nota: No todas las API cumplen con el estándar de Atom. Por ejemplo, algunas API permiten solo un elemento <author> por entrada; otras heredan el autor de la entrada del nivel del feed, lo que hace que el campo sea de solo lectura.

Después de que el servidor procesa una solicitud PATCH válida, muestra un código de estado HTTP 200, junto con una copia de la representación completa de la entrada actualizada.

Si prefieres que el servidor muestre solo ciertos elementos o atributos, puedes usar el parámetro de búsqueda fields con PATCH para solicitar una respuesta parcial.

Recursos adicionales

Los siguientes documentos de terceros pueden resultarte útiles:

Volver al principio