Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

rest - define REST web APIs and call them inline or asychronously

Table Of Contents

SYNOPSIS

package require Tcl 8.5
package require rest ?1.5?

::rest::simple url query ?config? ?body?
::rest::get url query ?config? ?body?
::rest::post url query ?config? ?body?
::rest::patch url query ?config? ?body?
::rest::head url query ?config? ?body?
::rest::put url query ?config? ?body?
::rest::delete url query ?config? ?body?
::rest::save name file
::rest::describe name
::rest::parameters url ?key?
::rest::parse_opts static required optional words
::rest::substitute string var
::rest::create_interface name

DESCRIPTION

There are two types of usage this package supports: simple calls, and complete interfaces. In an interface you specify a set of rules and then the package builds the commands which correspond to the REST methods. These commands can have many options such as input and output transformations and data type specific formatting. This results in a cleaner and simpler script. On the other hand, while a simple call is easier and quicker to implement it is also less featureful. It takes the url and a few options about the command and returns the result directly. Any formatting or checking is up to rest of the script.

Simple usage

In simple usage you make calls using the http method procedures and then check or process the returned data yourself

Interface usage

An interface to a REST API consists of a series of definitions of REST calls contained in an array. The name of that array becomes a namespace containing the defined commands. Each key of the array specifies the name of the call, with the associated configuration a dictionary, i.e. key/value pairs. The acceptable keys, i.e. legal configuration options are described below. After creating the definitions in the array simply calling rest::create_interface with the array as argument will then create the desired commands.

Example, Yahoo Weather:

package require rest

set yweather(forecast) {
   url      http://weather.yahooapis.com/forecastrss
   req_args { p: }
   opt_args { u: }
}
rest::create_interface yweather
puts [yweather::forecast -p 94089]

Examples

Yahoo Geo:

set ygeo(parse) {
    url http://wherein.yahooapis.com/v1/document
    method post
    body { arg documentContent }
}
ygeo::parse "san jose ca"
# "san jose ca" will be interpreted as if it were specified as the -documentContent option

Google Docs:

set gdocs(upload) {
    url http://docs.google.com/feeds/default/private/full
    body mime_multipart
}
gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata]

Delicious:

set delicious(updated) {
    url https://api.del.icio.us/v1/posts/update
    auth basic
}

rest::create_interface flickr

flickr::basic_auth username password

Flickr:

set flickr(auth.getToken) {
   url http://api.flickr.com/services/rest/
   req_args { api_key: secret: }
   auth { sign do_signature }
}

rest::create_interface flickr

proc ::flickr::do_signature {query} {
    # perform some operations on the query here
    return $query
}

INCLUDED

The package provides functional but incomplete implementations for the following services:

Please either read the package's implementation, or use rest::describe after loading it for their details.

Do not forget developers' documentation on the respective sites either.

TLS

The rest package can be used with https-secured services, by requiring the TLS package and then registering it with the http package it is sitting on top of. Example

package require tls
http::register https 443 ::tls::socket

TLS Security Considerations

This package uses the TLS package to handle the security for https urls and other socket connections.

Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and are likely influenced by the set of servers the application will talk to as well.

For example, in light of the recent POODLE attack discovered by Google many servers will disable support for the SSLv3 protocol. To handle this change the applications using TLS must be patched, and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below.

package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol

... your own application code ...

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category rest of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.