Visión general de la guía para programadores

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.

Google tiene como objetivo organizar mundial y ponerla a disposición de todas las personas para que la usen. Esto incluye hacer que la información sea accesible en contextos que no sean un navegador web y accesibles para los servicios ajenos a Google.

El protocolo de datos de Google proporciona un medio seguro para que los desarrolladores externos escriban nuevas aplicaciones que permitan a los usuarios finales acceder y actualizar los datos almacenados por muchos productos de Google. Los desarrolladores externos pueden usar el protocolo de datos de Google directamente o cualquiera de los lenguajes de programación admitidos que proporcionan las bibliotecas cliente.

Público

Este conjunto de documentos está dirigido a cualquier persona que desee comprender el protocolo de datos de Google. Incluso si solo quieres escribir código que use las bibliotecas cliente específicas del lenguaje, este conjunto de documentos puede ser útil si deseas comprender lo que sucede debajo de la capa de abstracción de biblioteca cliente y biblioteca.

Si buscas la Guía para programadores de una API específica, visita el directorio de API del protocolo de datos de Google.

Si deseas acceder a una API en tu lenguaje de programación favorito, visita la página de descarga de Bibliotecas cliente.

Información general

Varios productos de Google, como el Calendario y las Hojas de cálculo, proporcionan API que se basan en el Protocolo de datos de Google. Usted, el desarrollador, puede usar estas API para escribir aplicaciones cliente que brinden a los usuarios finales nuevas formas de acceder y manipular los datos que almacenan en esos productos de Google.

Nota: A veces, los productos de Google que proporcionan API se denominan servicios en estos y otros documentos relacionados.

Si escribes código que usa el protocolo de datos de Google directamente, este accede a la API mediante solicitudes HTTP como GET o POST. Con estas solicitudes, los datos que almacena el producto de Google se transfieren y se transmiten por transferencia en forma de feeds de datos. Los feeds de datos son simplemente listas estructuradas que contienen los datos. Históricamente, el formato del feed principal ha sido XML de AtomPub, pero ahora JSON, o JavaScript Object Notation, también está disponible como un formato alternativo.

Si prefieres no escribir código que realiza solicitudes HTTP directamente, puedes programar tu aplicación cliente con uno de los lenguajes de programación disponibles en el conjunto de bibliotecas cliente proporcionadas. Cuando haces esto, los detalles de las solicitudes HTTP se manejan con la biblioteca cliente. Debes escribir tu código en un nivel más conceptual mediante los métodos y clases específicos del lenguaje que proporciona la biblioteca cliente.

Consulta la documentación específica del producto a fin de obtener más información sobre los idiomas específicos disponibles para la API o la versión de la API que estás usando.

Versiones del protocolo

Comparación entre la versión 2.0 del protocolo y la versión 1.0 del protocolo

La primera versión del protocolo de datos de Google se desarrolló antes de que se completara el protocolo de publicación Atom. La segunda versión del protocolo de datos de Google cumple todas las normas RFC 5023 de Atom.

La versión 2.0 del protocolo de datos de Google también incluye asistencia para lo siguiente:

  • ETag de HTTP Un estándar web que ayuda a las aplicaciones cliente a aprovechar mejor el almacenamiento en caché HTTP. Los servicios incluidos en las bibliotecas cliente que admiten la versión 2.0 del protocolo controlan las ETag automáticamente.
  • Respuesta parcial y Actualización parcial (Experimental). Funciones que te permiten realizar solicitudes que transfieren menos datos Al solicitar solo la información que realmente necesitas o enviar actualizaciones que incluyan solo los datos que realmente deseas cambiar, tu aplicación cliente puede ser mucho más eficiente en el uso de recursos de red, CPU y memoria. En este momento, la respuesta parcial y la actualización parcial solo están disponibles para algunos productos. Consulta la documentación específica del producto para averiguar si tu API lo admite.

Actualiza tu aplicación

Si la API que usa se compiló sobre la última versión del protocolo, entonces la funcionalidad del Protocolo v2.0 se incluye en su documentación. En general, recomendamos que actualices tu aplicación cliente a la última versión disponible para tu API.

Actualiza un cliente basado en la biblioteca cliente

Si tu aplicación cliente usa una biblioteca cliente, como la biblioteca cliente de Java o .NET, puede contener una versión de la API que sea compatible con las características del protocolo v2.0. Para averiguarlo, consulte la documentación de la API del producto de Google que está usando para saber si se cumple lo siguiente:

  • Existe una versión de la API que admite las funciones del Protocolo de datos de Google versión 2.0.
  • La biblioteca cliente que estás utilizando también admite esa versión de API.

Si la biblioteca cliente lo admite y deseas actualizar la aplicación existente, solo tienes que descargar y usar la última versión de la biblioteca cliente. Todo tu código seguirá funcionando, y la biblioteca cliente se encargará de los cambios de protocolo v2.0 de forma interna.

Actualiza un cliente HTTP sin procesar

Si escribiste directamente tu aplicación cliente usando el protocolo de datos de Google, debes realizar estos cambios:

  • Solicitudes de versiones no predeterminadas. Agrega un encabezado de versión HTTP (GData-Version: X.0) a cada solicitud HTTP que envíes; en este caso, X es la versión de la API que admite las funciones del Protocolo de datos de Google v2.0. Como alternativa, agrega un parámetro de búsqueda (v=X.0) a la URL de cada solicitud, en la que X es la versión correcta de la API. Si no especificas una versión posterior, tus solicitudes se envían a la primera versión compatible de la API de forma predeterminada.
  • Simultaneidad optimista. Si usabas una versión de una API que admite la simultaneidad optimista, es posible que debas cambiar la actualización y borrar el código para usar ETags. Para obtener más información, consulta la sección sobre etiquetas ETag de la documentación de referencia del Protocolo de datos de Google y las secciones sobre las actualizaciones y las eliminaciones de la guía del desarrollador del protocolo para el servicio que usa la aplicación cliente.
  • URI automático o editado. Si tu cliente lleva un registro de los URI propios o de las ediciones de los feeds o entradas, ten en cuenta que esos URI pueden haber cambiado. Para obtener el URI nuevo, vuelve a solicitar el elemento con el URI anterior, pero marca la solicitud como una versión X.0, en la que X es la versión de la API que admite las funciones del protocolo de datos de Google versión 2.0. El servidor muestra la nueva representación de la entrada, incluidos los URI nuevos, que puedes almacenar en lugar de los anteriores.
  • URI de espacio de nombres. Si tu cliente almacena los URI de espacio de nombres de la API de Google Data Protocols de forma local o si tiene hard-coded, deberás actualizarlos:
    • Se cambió el espacio de nombres AtomPub (prefijo app) de http://purl.org/atom/app a http://www.w3.org/2007/app.
    • Se cambió el espacio de nombres de OpenSearch (prefijo openSearch) de http://a9.com/-/spec/opensearchrss/1.0/ a http://a9.com/-/spec/opensearch/1.1/.