API do Blogger: primeiros passos

Este documento explica como começar a usar a API Blogger.

Antes de começar

Criar uma Conta do Google

Confira se você tem uma Conta do Google configurada. Recomendamos que você use uma Conta do Google separada para fins de desenvolvimento e teste e se proteja contra perda acidental de dados. Se você já tem uma conta de teste, tudo certo. Acesse a interface do usuário do Blogger para configurar, editar ou ver seus dados de teste.

Conheça o Blogger

Se você não conhece os conceitos do Blogger, leia este documento e teste a interface do usuário antes de começar a programar. Este documento pressupõe que você esteja familiarizado com o Blogger, com conceitos de programação e formatos de dados da Web.

Saiba como autorizar solicitações e identificar seu aplicativo

Quando seu aplicativo solicita dados particulares, a solicitação precisa ser autorizada por um usuário autenticado com acesso a esses dados.

No caso dos dados públicos, a solicitação não precisa ser autorizada, mas precisa ser acompanhada por um identificador, como uma chave de API.

Para informações sobre como autorizar solicitações e usar chaves de API, consulte Autorizar solicitações e identificar seu aplicativo no documento "Como usar a API".

Informações básicas sobre a API Blogger

Conceitos do Blogger

O Blogger é baseado em cinco conceitos básicos:

  • Blogs: o conceito raiz da API. Um blog tem postagens e páginas. É o contêiner para metainformações do blog, como nome e descrição.
  • Postagens: uma postagem de blog é o item publicável que o autor do blog criou. Essas informações são atuais e refletem o que os autores querem publicar para o mundo agora. Entende-se que, com o tempo, o conteúdo das postagens de blog envelhece e se torna menos relevante.
  • Comentários: é onde as pessoas que não são o autor da postagem do blog reagem ao que ele escreveu. Tudo, de tijolos a buquês.
  • Páginas: uma página é um lugar para conteúdo estático, como informações biográficas ou formas de entrar em contato com o usuário. Geralmente, são informações atemporais que não mudam com muita frequência.
  • Usuários: um usuário é alguém que interage com o Blogger, seja como autor, administrador ou apenas leitor. Nos blogs públicos, os leitores podem ser anônimos, mas nos blogs particulares, eles precisam ser identificados pelo Blogger.

Modelo de dados da API Blogger

Um recurso é uma entidade individual de dados com um identificador exclusivo. A API JSON do Blogger opera em cinco tipos de recursos:

  • Recurso "Blogs": representa um blog.
  • Recurso "posts": representa uma postagem. Cada recurso "posts" é filho de um recurso "blogs".
  • Recurso "Comments": representa um comentário em uma postagem específica. Cada recurso "Comments" é filho de um recurso "Posts".
  • Recurso "Pages": representa uma página estática. Cada recurso "pages" é filho de um recurso "blogs".
  • Recurso "Users": representa um usuário não anônimo. Isso é usado para identificar o autor de uma página, postagem ou comentário.
O recurso "blogs" tem dois tipos de recursos filhos: "pages" e "posts". Um recurso de postagens pode ter recursos filhos de comentários.
Visão geral das relações entre recursos

O modelo de dados da API Blogger é baseado em grupos de recursos, chamados de coleções:

Coleção de blogs
Uma <span="apicollection">coleção de blogs consiste em todos os blogs a que um usuário tem direitos de acesso. É possível listar blogs por usuário ou recuperar um único blog por ID.</span="apicollection">
Coleção de postagens
Uma coleção de postagens consiste em todos os recursos de postagens em um recurso de blogs específico.
Coleta de comentários
Uma coleção de comentários consiste em todos os recursos de comentários em um recurso de postagens específico.
Coleção de páginas
Uma coleção de páginas consiste em todos os recursos de páginas em um recurso de blogs específico.
Coleção de usuários
Uma coleção de usuários consiste em todos os recursos de usuários no Blogger e, portanto, não pode ser listada. Um usuário pode recuperar o próprio recurso users (mas não de outras pessoas) por ID ou usando o identificador self.

Operações da API Blogger

É possível invocar vários métodos diferentes em coleções e recursos na API Blogger, conforme descrito na tabela a seguir.

Operação Descrição Mapeamentos HTTP REST
list Lista todos os recursos em uma coleção. GET em um URI de coleção.
get Recebe um recurso específico. GET em um URI de recurso.
getByUrl Procura e retorna um recurso por URL. GET com o URL transmitido como um parâmetro.
getByPath Procura um recurso pelo caminho dele. GET com o caminho transmitido como um parâmetro.
listByUser Lista os recursos de propriedade de um usuário. GET em uma coleção de propriedade do usuário.
search Pesquise recursos com base em um parâmetro de consulta. GET em um URL de pesquisa, com a consulta transmitida como um parâmetro.
inserir Crie um recurso em uma coleção. POST em um URI de coleção.
delete Exclui um recurso. DELETE em um URI de recurso.
patch Atualiza um recurso usando a semântica de patch. PATCH em um URI de recurso.
update Atualize um recurso. PUT em um URI de recurso.

A tabela abaixo mostra quais métodos são compatíveis com cada tipo de recurso. Todas as operações list e get em blogs particulares exigem autenticação.

Tipo de recurso
Métodos suportados
list get getByUrl getByPath listByUser search insert delete patch update
Blogs não sim sim não sim não não não não não
Postagens sim sim não sim não sim sim sim sim sim
Comentários sim sim não não não não não não não não
Páginas sim sim não não não não não não não não
Usuários não sim não não não não não não não não

Como chamar estilos

Há diversas maneiras de chamar a API:

REST

REST é um estilo de arquitetura de software que fornece uma abordagem conveniente e consistente para solicitar e modificar dados.

O termo REST é a abreviação de "Representational State Transfer (Transferência de Estado Representacional)". No contexto das APIs do Google, ele se refere ao uso de verbos HTTP para recuperar e modificar representações de dados armazenados pelo Google.

Em um sistema RESTful, os recursos são mantidos em um armazenamento de dados. Um cliente envia uma solicitação para que uma ação específica seja executada no servidor, como a criação, recuperação, atualização ou exclusão de um recurso. Essa ação é executada e uma resposta é enviada, geralmente no formato de uma representação do recurso especificado.

Nas APIs RESTful do Google, uma ação é especificada no cliente usando um verbo HTTP como POST, GET, PUT ou DELETE. Um recurso é definido por meio de um URI global exclusivo no seguinte formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Como todos os recursos da API têm URIs exclusivos acessíveis por HTTP, a REST permite o armazenamento em cache dos dados e é otimizada para funcionar na infraestrutura distribuída da Web.

As definições de método (em inglês) encontradas na documentação dos padrões HTTP 1.1 podem ser úteis. Nelas estão incluídas as especificações GET, POST, PUT e DELETE.

REST na API Blogger

As operações compatíveis do Blogger são mapeadas diretamente para verbos HTTP REST, conforme descrito em Operações da API Blogger.

O formato específico dos URIs da API Blogger é:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

A explicação completa dos URIs usados e os resultados de cada operação compatível na API estão resumidos no documento de referência da API Blogger.

Exemplos

Liste os blogs a que o usuário autenticado tem direitos de acesso:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

Acesse as postagens no blog code.blogger.com, que tem o ID 3213900:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST a partir de JavaScript

É possível invocar a API Blogger em JavaScript usando o parâmetro de consulta callback e fornecendo uma função de callback. Quando o navegador carrega o script, a função de callback é executada e a resposta é fornecida a ela. Essa abordagem permite gravar aplicativos avançados que mostram dados do Blogger sem exigir código do lado do servidor.

O exemplo a seguir recupera uma postagem do blog code.blogger.com depois que você substitui YOUR-API-KEY pela sua chave de API.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

Formato de dados

JSON

JSON (JavaScript Object Notation) é um formato de dados comum e independente de linguagem que oferece uma representação de texto simples das estruturas de dados arbitrárias. Para mais informações, acesse json.org (em inglês).