Wprowadzenie do GData

11 July 2008 Comments

GData to protokół i API służące do pobierania, szukania, edycji, dodawania i usuwania danych. GData wykorzystuje żądaniach HTTP: GET, POST, PUT i DELETE, a przesyłane dane zapisane są w formacie kanałów Atom. GData obsługuje też uwierzytelnianie. Protokół ten został opracowany przez Google w celu ułatwienia integracji posiadanych aplikacji między sobą, a także w celu udostępnienia API osobom trzecim, umożliwiając tym samym integrowanie innych aplikacji z usługami Google jak kalendarz czy dokumenty. Na stronach Google dostępna jest pełna specyfikacja protokołu, API dla poszczególnych usług, a także biblioteki dla różnych języków programistycznych ułatwiające korzystanie z API.

Załóżmy że na naszej stronie pod odnośnikiem /kanał mamy "kanał" Atom obsługujący protokół GData. By pobrać zawartość kanału wystarczy wysłać żądanie GET:

GET /kanał

Powodzenie operacji rozpoznamy po statusie 200 odpowiedzi serwera:

200 OK

Zwrócone dane (kanał nie zawiera wpisów) będą postaci:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Mój Kanał</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.strona.pl/kanał</id>
  <author>
    <name>Imię Nazwisko</name>
  </author>
  <link href="/kanał" rel="self"/>
</feed>

By dodać wpis wystarczy wysłać dane w formacie GData za pomocą żądania POST

POST /kanał

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Jan Kowalski</name> 
    <email>jan@kowalski.pl</email> 
  </author>
  <title type="text">Tytuł wpisu 1</title>
  <content type="text">To jest mój wpis</content>
</entry>

Nie podajemy elementów Atom takich jak "id", "link" czy "updated" - serwer je tworzy w odpowiedzi na przesłane żądanie. W przypadku udanej operacji serwer zwróci odpowiedź o statusie 201:

201 CREATED

Oraz "fragment" kanału zawierający dodane dane:

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Jan Kowalski</name> 
    <email>jan@kowalski.pl</email> 
  </author>
  <title type="text">Tytuł wpisu 1</title>
  <content type="text">To jest mój wpis</content>
</entry>

W celu wyszukania wpisów zawierających podaną frazę należy wysłać żądanie GET z parametrem q zawierającym szukaną frazę:

GET /kanał?q=wpis

Serwer zwróci odpowiedź ze statusem 200 w przypadku powodzenia:

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.strona.pl/kanał</id>
  <author>
    <name>Imię Nazwisko</name>
  </author>
  <link href="/kanał" rel="self"/>
  <entry>
    <id>1</id>
    <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Tytuł wpisu 1</title>
    <content type="text">To jest mój wpis</content>
  </entry>
</feed>

By zaktualizować istniejący wpis należy wysłać żądanie PUT z odnośnikiem edycji podanym dla danego wpisu w kanale atom (link rel="edit"). Jeżeli firewall blokuje żądania PUT można wysłać żądanie POST z modyfikacją nagłówka:

X-HTTP-Method-Override: PUT

Przy dodawaniu wpisu (co robiliśmy wcześniej) serwer generuje link edycji dla nowego wpisu (w przykładzie http://www.strona.pl/kanał/1/1/). Wysyłamy żądanie:

PUT /kanał/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Nowy Tytuł</title>
    <content type="text">To nowy wpis</content>
</entry>

Serwer odpowie:

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/2/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Nowy Tytuł</title>
    <content type="text">To nowy wpis</content>
</entry>

Zwróć uwagę że zmianie uległ link edycji (/2/ zamiast /1/). Ostatnia z liczb pełni rolę numeru wersji wpisu.

By usunąć wpis wysyłamy żądanie DELETE, lub w przypadku blokady na firewallu wysyłamy żądanie POST zawierające w nagłówku:

X-HTTP-Method-Override: DELETE

By skasować nasz wpis wystarczy wysłać żądanie:

DELETE /kanał/1/2/

W przypadku sukcesu serwer odpowie statusem 200

200 OK

RkBlog

Podstawy tworzenia stron www, 11 July 2008