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:
- Visão geral do Atom da IBM
- Definições de método do HTTP 1.1; especificação para
GET
,POST
,PUT
eDELETE
- Definições de código de status HTTP 1.1
- Como criar um protocolo REST
- Como criar serviços da Web da maneira REST
- Introdução técnica ao XML
- Namespaces XML por exemplo