3 Macro

The simplest approach creates wrapper functions for the web service at compile time. This reduces startup time for your application. Furthermore, it means that you don’t need to ship the service documents—they are "source code" just like your .rkt files.

(require (planet gh/gapi:1:=3/macro))

discovery-document-name may be either a fully qualified pathname, or a literal that is the name of one of the Available services.

Each defined function makes an HTTP request to the web service. The function takes keyword arguments. These values are supplied in the HTTP request to the service.

The web service responds with JSON, which is returned by the wrapper function as a jsexpr?. This library doesn’t try to marshal the response into structs. Instead you will need to understand its format and retrieve the information, for example (hash-ref js 'items) if the response contains a list of items.

Every Google services takes an optional key query parameter for a Google API key. The wrapper functions provide this as a #:key argument. As a convenience, the #:key argument defaults to the api-key Racket parameter. Put your Google API key in a file named .google-api-key in your home directory—in other words, ~/.google-api-key.

As another convenience, see the paged form which simplifies making repeated calls to a service that returns results in small "pages" (batches of results).

Example:

#lang racket

(require (planet gh/gapi/macro))

(require-gapi-doc urlshortener.v1.js)

(define orig-url "http://www.racket-lang.org/")

(define js-insert (urlshortener-url-insert #:longUrl orig-url))

(define short-url (dict-ref js-insert 'id))

(define js-get (urlshortener-url-get #:shortUrl short-url))

(define long-url (dict-ref js-get 'longUrl))

(printf "~s was shortened to ~s, which expanded back to ~s: ~a"

orig-url short-url long-url

(if (equal? orig-url long-url) "Yay!" "Boo!"))