-
Notifications
You must be signed in to change notification settings - Fork 9
[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.
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.
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.
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.
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.
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.
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.
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.
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] 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 tohttp://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 tohttp://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 tohttp://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.
You can initialize [rest] with creation arguments as well as with the [init( message. Both methods require 0, 1 or 4 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.
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
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).
[rest] can use basic HTTP authentication as well as cookie 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.
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:
- Set the base URL to
https://www.example.com - Send a POST request to
https://www.example.com/login.phpwith the data ofuser=username&password=myspecialpassword. - 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 lineSet-Cookie:login=username;will savelogin=username. - All later requests will include the HTTP request header
Cookie:with the saved value, in the result above, this meansCookie: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] 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 tohttp://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 tohttp://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.
You can initialize [oauth] with creation arguments as well as with the [init( message. Both methods require 0, 3 or 5 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.
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.
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.
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.
This is the default method and is used by most services.
If you want to set this method explicitely, use the [method HMAC( message.
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.
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-----(