## [rest] And [oauth]: Making HTTP Requests

The library contains two distinct objects for RESTful web requests, `[rest]` and `[oauth]` . Both objects have a lot of functionality in common, but are used in differenct scenarios:

`[rest]` is used for simple RESTful requests, and can issue `GET` , `POST` , `PUT` , `DELETE` , `HEAD` , `PATCH` , `OPTIONS` and `TRACE` .

`[oauth]` is used for OAuth 1.0 requests, and can issue `GET` , `POST` , `PUT` , `DELETE` , `HEAD` , `PATCH` , `OPTIONS` and `TRACE` .

## Common Functionality

Both objects have three outlet, with the middle outlet outputting the content of the HTTP request, the left outlet outputs a `bang` after a successful operation, and the right outlet is used for error handling.

Both `[rest]` and `[oauth]` can be initialized with a base URL and additional parameters either as creation arguments or using the `[init(` message.

Both objects can issue GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS, and TRACE requests.

After a successful HTTP request (HTTP stati with a numerical value of at least 200 and less than 300), both objects will output the message body on the middle outlet, followed by a `bang` on the left outlet. HTTP redirects by stati 301 and 302 are followed by the objects.

### Setting HTTP Timeout And Cancelling Requests

Using the `[timeout(` message, you can set and clear the timeout to wait for a response from the object. Issuing the message with a numerical value will set the timeout to the value in milliseconds, the message without any parameter will clear the value, and the object will wait for a response infinitely.

You can cancel an ongoing request using the `[cancel(` message. If the request has already reached the web server, then an action on the server may already be in progress, only waiting for a response is then cleared.

As the objects are operating in a seperate thread, cancelling a request may need some time to cleanup the object, so you may need to wait for a small timespan to be available again. If you want to cancel a request and issue a new one right after it, the object may still be locked. Use a small delay to start the new request, 10 milliseconds is a good start for twiddling with the value.

### Setting HTTP Headers

With the `[header(` message, you can set an additional HTTP header. This message needs at least one additional symbol parameter. More than one additional parameters will be concatenated with a space.

Sending the message again will add new HTTP headers and not clear existing ones.

To clear the HTTP headers, use `[header_clear(` without any parameter.

Examples:

Some webservices return different values for different `Accept:` HTTP headers. In that case, you can use `[header Accept: application/json(` to add the line `Accept: application/json` to the HTTP request.

Github requires a `User-Agent:` HTTP header to return value. You can use `[header User-Agent: My User Agent(` to set the value.

### Disabling Checking TLS Certificates

If the server uses a self-signed TLS certificate or the certificate authority (CA) is not recognised by your setup, an SSL secured request will fail with an error message of `SSL peer certificate or SSH remote key was not OK` and a `51 SSL peer certificate or SSH remote key was not OK` on the right outlet. To disable checking for valid certificates, use a message of `[sslcheck 0(` . You can reenable the check with `[sslcheck 1(`

Caveat:

Before doing that, you should be aware of the risks .

### Using Proxies

You can configure the usage of a proxy with `[proxy(` . This message takes 0, 1 or 3 parameters. Use one parameter to set the URL of the proxy including protocol and port number. If your proxy needs username and password, then add those as second and third additional parameter. To clear the proxy settings, use an empty `[proxy(` message.

Examples:

`[proxy http://127.0.0.1:1234(` will set the proxy without username and password.

`[proxy socks5://127.0.0.1:2050 me mysecret(` will set the proxy using username `me` and password `mysecret` .

### Downloading to File

The `[file(` message with an additional parameter will set the path to a file, where the downloaded content will be stored. This will not check immediately, if the file is writable, as this property in the file system may change any time.

If a file path is set, then a successful download will not be output on the middle outlet, but will be written to that location. If that location is not writable to Pd, then the content will generate output on the middle outlet regardless, and post a message to the console.

The left and right outlet of `[rest]` and `[oauth]` will output the same values as with a other HTTP request.

To clear the download location, use a `[file(` message without a parameter.

### Consuming Streaming API

If a service returns its data with a streaming API, you can output the data whenever a chunk is received. To set the mode to streaming, send a message `[mode stream(` to the object. To return to the standard blocking mode, send `[mode block(` to the object. The mode can be set during processing of a request.

This is useful for webservices that keep connections open and send data on events, e.g. Twitter streaming API.

### Error handling

If the HTTP result is not successful as defined above, then the right outlet will output a float with the HTTP error code, and on the console the HTTP status will be output as an error message, e.g. `HTTP error while performing request: 404` on console, `404` on right outlet.

If there is an error during the HTTP request (timeout, DNS problems), then the right outlet will output a list with the cURL error code and the message, while additionally outputting the message on the console, e.g. `Error while performing request: Timeout was reached` on console, `28 Timeout was reached` on right outlet.

With this information you can distinguish a HTTP error from a cURL error, and react accordingly.

## `[rest]` : HTTP Requests

`[rest]` accepts the following HTTP verbs: GET, POST, PUT, DELETE, HEAD, PATCH, TRACE, and OPTIONS. The messages corresponding to the requests are `[GET(` , `[POST(` , `[PUT(` , `[DELETE(` , `[HEAD(` , `[PATCH(` , `[TRACE(` , and `[OPTIONS(` , and these messages need at least one additional parameter, the URL of the requests. If you have set a base URL, the URL is concatenated with the base URL.

Examples:

- If the base URL is set to `http://www.example.com/` , then `[GET data/1(` will send an HTTP GET request to `http://www.example.com/data/1` .
- If no base URL is set, then `[DELETE http://www.example.com/data/1(` will send an HTTP DELETE request to `http://www.example.com/data/1` .
- If the base URL is set to `http://www.example.com/` , then `[GET http://www.example.com/data/1(` will send an HTTP GET request to `http://www.example.com/http://www.example.com/data/1` (and probably result in a 404 error).

`[POST(` , `[PUT(` and `[PATCH(` requests usually need additional data. This data is set as additional parameters. These parameters are concatenated with a space in between.

Example:

`[POST http://www.example.com/data id=1&name=my%20name(` will send an HTTP POST request to `http://www.example.com/data` and include `id=1&name=my%20name` as POST parameters.

### Initialization

You can initialize `[rest]` with creation arguments as well as with the `[init(` message. Both methods require 0, 1 or 4 parameters.

#### No Parameters

If you use no parameters on creation or in the `[init(` message, then no base URL is set and any previously set cookie data is deleted.

#### 1 Parameter

If you use exactly 1 parameter, then this is set as the base URL. Previously set cookie data is deleted.

Example:

`[init https://www.example.com(` will set the base URL to `https://www.example.com`

#### 4 Parameters

If you use exactly 4 parameters, then the parameters set the base URL, login URL, username and password for cookie authentication in this order. `[rest]` will then try to login at the specified URL with the username and password and set a cookie for later requests (see below).

### Different Authentication Methods

`[rest]` can use basic HTTP authentication as well as cookie authentication.

#### Basic HTTP Authentication

If a webservice is configured with basic HTTP authentication, then include the credentials in the URL after the protocol part, separating username and password by a colon, and before the remainder of the correct URL.

Example:

The service at `https://www.example.com/` needs authentication, and your username is myname, your password is mysupersecret. To access the data, use `[GET https://myname:mysupersecret@www.example.com(` .

This works in the base URL as well as in any HTTP request. As the part `myname:mysupersecret` gets converted to an HTTP request header before actually sending the request, a TLS secured connection will encrypt the credentials.

Alternatively, you can also set the HTTP header manually.

#### Cookie Authentication

If you initialize `[rest]` with 4 parameters, then the object will try to log in using the parameters.

Example:

`[init https://www.example.com /login.php username myspecialpassword(` will do the following:

1. Set the base URL to `https://www.example.com`
2. Send a POST request to `https://www.example.com/login.php` with the data of `user=username&password=myspecialpassword` .
3. Wait for the returned data. If the login is successful, then it will parse the HTTP response header for a line starting with `Set-Cookie:` . The remainder of this line (without the trailing semicolon) will be saved for later requests, e.g. the line `Set-Cookie:login=username;` will save `login=username` .
4. All later requests will include the HTTP request header `Cookie:` with the saved value, in the result above, this means `Cookie:login=username` .

Only the first returned cookie will be used, and only one value at a time will be saved. The parameters for sending the username and password to the server cannot be renamed. This works e.g. for CouchDB logins.

## `[oauth]` : OAuth 1.0 Requests

`[oauth]` accepts the following HTTP verbs: GET, POST, PUT, DELETE, HEAD, PATCH, TRACE, and OPTIONS. The messages corresponding to the requests are `[GET(` , `[POST(` , `[PUT(` , `[DELETE(` , `[HEAD(` , `[PATCH(` , `[TRACE(` , and `[OPTIONS(` , and these messages need at least one additional parameter, the URL of the requests relative to the base URL.

Examples:

- If the base URL is set to `http://www.example.com/` , then `[GET data/1(` will send an HTTP GET request to `http://www.example.com/data/1` .
- If the base URL is set to `http://www.example.com/` , then `[GET http://www.example.com/data/1(` will send an HTTP GET request to `http://www.example.com/http://www.example.com/data/1` (and probably result in a 404 error).

`[POST(` , `[PUT(` and `[PATCH(` requests usually need additional data. This data is set as additional parameters. These parameters are concatenated with a space in between.

Example:

If the base URL is set to `http://www.example.com/` , then `[POST data id=1&name=my%20name(` will send an HTTP POST request to `http://www.example.com/data` and include `id=1&name=my%20name` as POST parameters.

### Initialization

You can initialize `[oauth]` with creation arguments as well as with the `[init(` message. Both methods require 0, 3 or 5 parameters.

#### No Parameters

If you use no parameters on creation or in the `[init(` message, then no base URL is set and any previously set credential data is deleted.

#### 3 Parameter

If you use exactly 3 parameter, then the parameters set the base URL, the consumer key (client key), and the consumer secret (client secret) in this order. Your access token and secret (token credentials) will be deleted.

After using this value, `[oauth]` will be able to identify itself as a valid client to the server, but will not be able to invoke HTTP requests on behalf of a verified user. Usually, this is used to get token credentials for a user.

Example:

`[init https://www.example.com my_client_key my_client_secret(` will set the base URL to `https://www.example.com` , the client key to `my_client_key` , and the client secret to `my_client_secret` .

#### 5 Parameters

If you use exactly 5 parameter, then the parameters set the base URL, the consumer key (client key), the consumer secret (client secret), the access token, and the access secret in this order.

Example:

`[init https://www.example.com my_client_key my_client_secret my_token my_access_secret(` will set the base URL to `https://www.example.com` , the client key to `my_client_key` , the client secret to `my_client_secret` , the access token to `my_token` , and the access secret to `my_access_secret` .

### OAuth Signature Method

Signatures are needed to verify the content of your HTTP request on the server-side and authenticate the credentials. OAuth 1.0 has three methods for generating signatures: HMAC-SHA1, plaintext and RSA-SHA1. These methods can be set using the `[method(` message.

#### HMAC-SHA1

This is the default method and is used by most services.

If you want to set this method explicitely, use the `[method HMAC(` message.

#### Plaintext

If you set `[oauth]` to use this method, your credentials are sent in plaintext, i.e. anyone can read your credentials from the sent data. This method is discouraged and only safe, if you use TLS secured connections and not use `[GET(` requests, as the data in that case is included in the URL.

The message to set this method is `[method PLAINTEXT(` . Because of the inherent insecurity, a warning is displayed on the Pd console.

#### RSA-SHA1

Instead of using client and access credentials, this method uses an RSA private key to sign the requests. You will still need to provide the credentials to `[oauth]` , but these values will not be used. Set the values to dummy values. This will only work, if your version of liboauth is at least 1.0.1, in prior versions, this is not implemented, and a warning will be displayed on the Pd console.

The message to set this method is `[method RSA the_RSA_private_key(` .

Example:

    [method RSA -----BEGIN PRIVATE KEY-----
    MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBALRiMLAh9iimur8V
    A7qVvdqxevEuUkW4K+2KdMXmnQbG9Aa7k7eBjK1S+0LYmVjPKlJGNXHDGuy5Fw/d
    7rjVJ0BLB+ubPK8iA/Tw3hLQgXMRRGRXXCn8ikfuQfjUS1uZSatdLB81mydBETlJ
    hI6GH4twrbDJCR2Bwy/XWXgqgGRzAgMBAAECgYBYWVtleUzavkbrPjy0T5FMou8H
    X9u2AC2ry8vD/l7cqedtwMPp9k7TubgNFo+NGvKsl2ynyprOZR1xjQ7WgrgVB+mm
    uScOM/5HVceFuGRDhYTCObE+y1kxRloNYXnx3ei1zbeYLPCHdhxRYW7T0qcynNmw
    rn05/KO2RLjgQNalsQJBANeA3Q4Nugqy4QBUCEC09SqylT2K9FrrItqL2QKc9v0Z
    zO2uwllCbg0dwpVuYPYXYvikNHHg+aCWF+VXsb9rpPsCQQDWR9TT4ORdzoj+Nccn
    qkMsDmzt0EfNaAOwHOmVJ2RVBspPcxt5iN4HI7HNeG6U5YsFBb+/GZbgfBT3kpNG
    WPTpAkBI+gFhjfJvRw38n3g/+UeAkwMI2TJQS4n8+hid0uus3/zOjDySH3XHCUno
    cn1xOJAyZODBo47E+67R4jV1/gzbAkEAklJaspRPXP877NssM5nAZMU0/O/NGCZ+
    3jPgDUno6WbJn5cqm8MqWhW1xGkImgRk+fkDBquiq4gPiT898jusgQJAd5Zrr6Q8
    AO/0isr/3aa6O6NLQxISLKcPDk2NOccAfS/xOtfOz4sJYM3+Bs4Io9+dZGSDCA54
    Lw03eHTNQghS0A==
    -----END PRIVATE KEY-----(