Princípios básicos do protocolo de APIs de dados do Google

Este documento descreve os princípios básicos do protocolo usados pelas APIs de dados do Google, inclusive exemplos de como é uma consulta, como são os resultados e assim por diante.

Para mais informações sobre as APIs de dados do Google, consulte o documento do Guia do desenvolvedor de dados do Google e o Guia de referência.

Público-alvo

Este documento é destinado a qualquer pessoa que queira entender a ideia geral do formato e protocolo XML usados pelas APIs de dados do Google.

Mesmo que você queira apenas criar um código que usa as bibliotecas de cliente específicas da linguagem, é recomendável ler este documento para entender o que está acontecendo abaixo da camada de abstração da biblioteca de cliente.

Neste documento, pressupomos que você tenha noções básicas sobre XML, namespaces, feeds distribuídos e solicitações GET, POST, PUT e DELETE em HTTP, além do conceito de "recurso" HTTP. Para mais informações, consulte a seção Recursos adicionais deste documento.

Este documento não depende de nenhuma linguagem de programação específica. Seu cliente pode interagir com o servidor usando qualquer linguagem de programação que permita emitir solicitações HTTP e analisar respostas baseadas em XML.

Exemplos

Os exemplos a seguir mostram solicitações de protocolo da API de dados simples que você pode enviar para um serviço genérico e os resultados que pode receber. Para ver exemplos de como enviar as solicitações usando várias linguagens de programação, consulte as amostras e as bibliotecas de cliente específicas de cada linguagem. Para ver informações sobre como usar as APIs de dados do Google com serviços do Google específicos, consulte a documentação específica do serviço.

Solicitar um feed ou outro recurso

Suponha que haja um feed chamado /myFeed e suponha que ele não contenha nenhuma entrada. Para vê-lo, envie a seguinte solicitação ao servidor:

GET /myFeed

O 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>

Embora o feed não contenha entradas, ele contém metadados, como um título e o nome de um autor.

Inserir uma nova entrada

Para criar uma nova entrada, envie uma solicitação POST e forneça a representação XML da nova entrada:

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>

Observe que você não fornece os elementos <id>, <link> ou <updated> padrão do Atom. O servidor os cria em resposta à solicitação POST. Observe também que o autor de um feed não precisa ser a mesma pessoa que o autor da entrada.

O 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>

Como pesquisar uma string

Para fazer uma pesquisa de texto completo por uma string específica, ao usar um serviço compatível com pesquisas de texto completo, envie uma solicitação GET com o parâmetro q. Para mais informações sobre parâmetros de consulta, consulte Solicitações de consulta no documento de referência do protocolo.

GET /myFeed?q=This

O servidor responde com todas as entradas que correspondem à string de pesquisa This. Nesse caso, há apenas uma resposta.

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>

Como atualizar uma entrada

Para atualizar uma entrada existente, use PUT, com o URI de edição da entrada (conforme fornecido pelo servidor no exemplo anterior, no elemento <link rel="edit">).

Se o firewall não permitir PUT, faça uma POST de HTTP e defina o cabeçalho de modificação do método da seguinte maneira:

X-HTTP-Method-Override: PUT

No exemplo a seguir, estamos mudando o texto da entrada de seu valor antigo ("Esta é minha entrada") para um novo valor ("Esta é minha primeira entrada"):

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>

O 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>

O URI de edição foi alterado. Agora ele termina com "/2/", em vez de "/1/". O número final no URI de edição é um número de versão. Para mais informações sobre versões, consulte a seção Simultaneidade otimista do documento de referência do protocolo.

Para ver a nova entrada no contexto, solicite todo o recurso novamente:

GET /myFeed

O 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>

Como excluir uma entrada

Para excluir uma entrada existente, envie uma solicitação DELETE, usando o URI de edição da entrada (conforme fornecido pelo servidor no exemplo anterior).

Se o firewall não permitir DELETE, faça uma POST de HTTP e defina o cabeçalho de modificação do método da seguinte maneira:

 X-HTTP-Method-Override: DELETE

O exemplo a seguir exclui uma entrada:

DELETE /myFeed/1/2/

O servidor responde:

200 OK

Faça outro GET para ver se o feed agora não contém entradas:

GET /myFeed

O 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>

Se a exclusão falhar, o servidor vai responder com um código de erro. Para mais informações, consulte os códigos de status HTTP no documento de referência do protocolo.

Outros recursos

Os seguintes documentos de terceiros podem ser úteis:

Voltar ao início