| rest(3tcl) | A framework for RESTful web services | rest(3tcl) |
rest - define REST web APIs and call them inline or asychronously
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
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.
In simple usage you make calls using the http method procedures and then check or process the returned data yourself
These commands are all equivalent except for the http method used. If you use simple then the method should be specified as an option in the config dictionary. If that is not done it defaults to get. If a body is needed then the config dictionary must be present, however it is allowed to be empty.
The config dictionary supports the following keys
Two quick examples:
Example 1, Yahoo Boss:
set appid APPID
set search tcl
set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]]
set res [rest::format_json $res]
Example 2, Twitter:
set url http://twitter.com/statuses/update.json
set query [list status $text]
set res [rest::simple $url $query {
method post
auth {basic user password}
format json
}]
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]
The result of the command is the empty string
The result of the command is the empty string.
If key is specified the command will not return the entire dictionary, but only the value of that key.
The result of the command is a list containing two elements. The first element is a dictionary containing the parsed options and their values. The second element is a list of the remaining words.
The values to substitute are found in the variable var, which is expected to contain a dictionary mapping from the option identifiers to replace to their values. Note that option identifiers which have no key in var are replaced with the empty string.
The option identifiers in string have to follow the syntax %...% where ... may contain any combination of lower-case alphanumeric characters, plus underscore, colon and dash.
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 legal keys and their meanings are:
The value of this option is treated as a command prefix which is invoked when the HTTP call is complete. The prefix will receive at least two additional arguments, the name of the calling procedure and the status of the result (one of OK or ERROR), in this order.
In case of OK a third argument is added, the data associated with the result.
If and only if the ERROR is a redirection, the location redirected to will be added as argument. Further, if the configuration key error-body is set to true the data associated with the result will be added as argument as well.
The http request header will be available in that procedure via upvar token token.
If not specified no transformation is done.
The command (prefix) must accept a single argument, the query (a dictionary) to transform, and must return the modified query (again as dictionary) as its result. The request body is accessible in the transform command via upvar body body.
If not specified no transformation is done.
The command (prefix) must accept a single argument, the result to transform, and must return the modified result as its result.
The http request header is accessible in the transform command via upvar token token
If not specified no transformation is done.
The command (prefix) must accept a single argument, the result to transform, and must return the modified result as its result.
The http request header is accessible in the transform command via upvar token token
The first expression is checks the OK condition, it must return true when the result is satisfactory, and false otherwise.
The second expression is the ERROR condition, it must return false unless there is an error, then it has to return true.
See callback above for more information.
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
}
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.
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
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 [http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html] 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 ...
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 [http://core.tcl.tk/tcllib/reportlist]. 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.
| 1.5 | tcllib |