rest-help.pd

#N canvas 209 73 1011 704 10;
#X declare -path purest_json;
#X text 55 178 - object for HTTP communication with REST webservices;
#X obj 18 176 rest;
#X obj 450 468 rest;
#X text 466 107 By default \, requests do not timeout. To set a maximal time in milliseconds \, set a value with [timeout( message. To clear the value and return to the default \, use an empty [timeout( message.;
#X msg 469 166 timeout 2000;
#X msg 569 166 timeout;
#X msg 594 415 sslcheck 0;
#X msg 691 414 sslcheck 1;
#X obj 18 198 oauth;
#X text 55 197 - object for HTTP communication with OAuth webservices;
#N canvas 148 110 1044 412 oauth-specific 0;
#X obj 29 53 oauth http://example.com/ CLIENTKEY CLIENTSECRET ACCESSTOKEN ACCESSSECRET;
#X msg 31 205 method PLAINTEXT;
#X obj 31 304 oauth;
#X msg 82 234 method HMAC;
#X msg 91 262 method RSA privatekey;
#N canvas 551 129 913 749 RSA 0;
#X msg 131 448 GET /echo_api.php?method=foo&bar=baz;
#X msg 128 491 POST /echo_api.php?method=foo&bar=baz;
#X obj 92 539 oauth;
#X msg 114 83 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-----;
#X text 481 33 You need to set client secret and access secret with the [init( message or as arguments for [oauth] \, but these will be ignored with the RSA key;
#X obj 92 608 print status-rsa;
#X obj 202 608 print data-rsa;
#X obj 202 581 spigot;
#X obj 235 555 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X msg 78 35 init https://example.com/oauth/example key this_is_ignored accesskey this_is_ignored;
#X connect 0 0 2 0;
#X connect 1 0 2 0;
#X connect 2 0 5 0;
#X connect 2 1 7 0;
#X connect 3 0 2 0;
#X connect 7 0 6 0;
#X connect 8 0 7 1;
#X connect 9 0 2 0;
#X restore 333 190 pd RSA;
#X text 29 135 The method message will set the OAUTH signature method. Default is HMAC (HMAC-SHA1). For RSA (RSA-SHA1) you have to submit your private key. If your version of liboauth does not support RSA-SHA1 signatures \, you will receive an error message.;
#X msg 523 55 GET /echo_api.php?method=foo&bar=baz;
#X msg 541 100 POST /echo_api.php?method=foo&bar=baz;
#X obj 489 142 oauth;
#X text 27 7 Set the base url \, consumer key and secret (client credentials) \, and optionally access token and secret (token credentials) at creation or use [init( message.;
#X obj 413 211 print status;
#X obj 502 211 print data;
#X obj 502 177 spigot;
#X obj 535 151 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X msg 489 9 init https://www.example.com/oauth/example key secret accesskey accesssecret;
#X connect 1 0 2 0;
#X connect 3 0 2 0;
#X connect 4 0 2 0;
#X connect 7 0 9 0;
#X connect 8 0 9 0;
#X connect 9 0 11 0;
#X connect 9 1 13 0;
#X connect 13 0 12 0;
#X connect 14 0 13 1;
#X connect 15 0 9 0;
#X restore 196 498 pd oauth-specific;
#X text 19 230 Most methods work the same for [rest] and [oauth] \, only some methods differ. The differences are outlined below.;
#X obj 22 429 urlparams;
#N canvas 137 61 404 367 rest-specific 0;
#N canvas 699 67 413 419 cookie-auth 0;
#X text 15 75 This will try to log you in on creation. It will call the url http://example.com/login-page and post username=myusername&password=mypass to the page.;
#X text 15 124 When this returns a cookie \, the cookie will be saved and included in every request \, as long as the base url does not change.;
#X text 15 173 Please keep in mind \, that passwords in Pd patches are stored in plain text \, especially when you use code hosting services. Better store your passwords in a seperate file or application and use [textfile] or OSC for getting the data.;
#X text 19 234 This;
#X obj 17 54 rest http://example.com/ login-page myusername mypass;
#X obj 20 253 rest http://example.com/ login-page myusername mypass;
#X obj 20 327 rest;
#X msg 20 293 init http://example.com/ login-page myusername mypass;
#X text 19 273 is the same as this after clicking the [init( message;
#X text 20 353 To clear your stored authentication cookie \, send a [init( message with no additional parameters \, or with only one parameter. The latter will send only the base url \, but will not try to log you in.;
#X text 15 6 Basic cookie authentication is possible with [rest] \, as long as the service uses some guidelines \, that are adopted from CouchDB.;
#X connect 7 0 6 0;
#X restore 8 316 pd cookie-auth;
#X text 6 296 Using cookie authentication with [rest];
#N canvas 548 57 860 439 CouchDB-basics 0;
#X text 469 71 CRUD documents:;
#X text 15 10 Basic CRUD methods for databases and individual documents are done with three HTTP methods: PUT \, GET and DELETE. PUT is used for creating and updating data \, GET is used for retrieving data \, while DELETE is used for deleting data. This is best explained with some examples:;
#X text 15 81 CRUD databases:;
#X text 15 100 PUT http://localhost:5984/pd-test;
#X text 15 119 This will create a database "pd-test" on the server localhost. If the operation is successful \, CouchDB will return a JSON object starting with a key of "ok" and a message as value for that key. If creating the database is not possible \, you will get a key "error" and the reason for the failure as its value.;
#X text 15 203 GET http://localhost:5984/pd-test;
#X text 15 222 This will get some info on the database \, including the count of stored documents as "doc_count". If getting the database is not possible you will receive a key "error" and the reason for the failure as its value.;
#X text 15 280 DELETE http://localhost:5984/pd-test;
#X text 15 299 This will delete the database if possible. BEWARE: You won't get prompted for confirmation \, CouchDB will delete the database without any warning including all stored documents. This will return "ok" or "error" as a key.;
#X text 469 122 This will create or update a document with the ID "object-name" in the database "pd-test". The database must be created first. If a document with the ID "object-name" already exists \, you must include the revision \, that you can get with the GET method (see below). On error CouchDB will return a key of "error" and the reason for the error as its value. Data for the object must be provided as JSON data in the request header.;
#X text 469 232 GET http://localhost:5984/pd-test/object-name;
#X text 469 251 This will retrieve the document "object-name" from the database "pd-test". This will return the document as a JSON object \, including the ID with the key "_id" and the revision code with the key "_rev". The latter value is needed for updating or deleting the object from the table to prevent concurrent updates.;
#X text 469 335 DELETE http://localhost:5984/pd-test/object-name;
#X text 469 354 This will delete the document if possible. You will need to provide the revision for the document. You will receive data with a key of "ok" or "error" and information as value.;
#X text 469 90 PUT http://localhost:5984/pd-test/object-name data-as-json-string;
#X text 15 357 All these request \, PUT \, GET and DELETE can be done with [rest] \, you can even issue POST requests to a CouchDB server. If you want to do complex data operations on a CouchDB \, please refer to the manual: http://guide.couchdb.org/;
#X restore 9 190 pd CouchDB-basics;
#N canvas 563 47 932 955 couchdb 0;
#X msg 170 173 bang;
#X obj 446 470 list trim;
#X msg 348 508 0;
#X obj 391 497 t b b;
#X msg 383 535 1;
#X obj 78 616 print error message;
#N canvas 574 80 450 431 create-sequencer-data 0;
#X obj 2 10 inlet;
#X obj 2 348 outlet;
#X obj 32 300 + 1;
#X obj 2 323 pack f s;
#X obj 2 244 json-encode;
#X obj 2 271 t b a;
#X obj 2 300 0;
#X msg 80 244 0;
#X obj 90 10 inlet;
#X obj 2 83 list append;
#X msg 2 60 440 2000 880 1000 440 1000 1320 500 880 2000;
#X obj 2 106 list split 2;
#X obj 90 173 spigot;
#X msg 123 145 0;
#X msg 152 149 1;
#X obj 2 37 t b b b;
#X msg 2 220 clear \, add pitch \$1 \, add duration \$2 \, bang;
#X obj 15 174 list;
#X connect 0 0 15 0;
#X connect 2 0 6 1;
#X connect 3 0 1 0;
#X connect 4 0 5 0;
#X connect 5 0 6 0;
#X connect 5 1 3 1;
#X connect 6 0 2 0;
#X connect 6 0 3 0;
#X connect 7 0 6 1;
#X connect 8 0 12 0;
#X connect 9 0 11 0;
#X connect 10 0 9 0;
#X connect 11 0 16 0;
#X connect 11 1 17 1;
#X connect 11 2 13 0;
#X connect 12 0 17 0;
#X connect 13 0 12 1;
#X connect 14 0 12 1;
#X connect 15 0 10 0;
#X connect 15 1 7 0;
#X connect 15 2 14 0;
#X connect 16 0 4 0;
#X connect 17 0 11 0;
#X restore 170 200 pd create-sequencer-data;
#X text 24 45 1 Sets the base URL.;
#X text 167 155 3 Creates some sequencer data and stores the data in pd-test. Objects contain "pitch" and "duration"., f 107;
#X text 328 189 4 Start sequencer and get first object;
#X obj 329 236 f;
#X obj 357 238 + 1;
#X obj 446 501 route pitch duration;
#X obj 418 533 pack f f f;
#X obj 338 627 unpack f f f;
#X obj 407 653 del;
#X obj 132 509 print data;
#X text 446 220 5 Get database pd-test;
#X text 446 275 6 Delete database pd-test;
#X msg 445 240 GET pdtest;
#X msg 72 134 PUT pdtest;
#X msg 170 224 PUT pdtest/\$1 \$2;
#X msg 448 293 DELETE pdtest;
#X msg 329 265 GET pdtest/\$1;
#X msg 329 208 0;
#X obj 338 570 spigot 1;
#X obj 750 503 spigot;
#X obj 783 469 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000 #000000 0 1;
#X obj 302 474 t b a b;
#X text 544 327 toggle only when using sequencer;
#X msg 302 506 0;
#X obj 372 673 osc~;
#X obj 433 720 *~ 0;
#X obj 433 746 dac~;
#X obj 391 436 json-decode;
#X obj 281 384 rest;
#X msg 23 65 init http://puredata:puredata@localhost:5984/;
#X text 3 14 This example uses a user named "puredata" and password "puredata" on a local instance that is able to create and delete databases., f 131;
#X text 70 100 2 Creates database pd-test on server with base URL. If you do not set the base URL \, then you can also issue this command with [PUT http://puredata:puredata@localhost:5984/pd-test/(, f 122;
#X obj 132 489 spigot;
#X obj 165 463 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000 #000000 0 1;
#X obj 199 249 print PUT-command;
#X connect 0 0 6 0;
#X connect 1 0 12 0;
#X connect 2 0 25 1;
#X connect 3 0 4 0;
#X connect 3 1 13 0;
#X connect 4 0 25 1;
#X connect 6 0 21 0;
#X connect 10 0 11 0;
#X connect 10 0 23 0;
#X connect 11 0 10 1;
#X connect 12 0 13 1;
#X connect 12 1 13 2;
#X connect 13 0 25 0;
#X connect 14 1 31 0;
#X connect 14 2 15 0;
#X connect 15 0 26 0;
#X connect 19 0 35 0;
#X connect 20 0 35 0;
#X connect 21 0 35 0;
#X connect 21 0 41 0;
#X connect 22 0 35 0;
#X connect 23 0 35 0;
#X connect 24 0 10 0;
#X connect 25 0 14 0;
#X connect 26 0 10 0;
#X connect 27 0 26 1;
#X connect 27 0 32 1;
#X connect 28 0 30 0;
#X connect 28 1 5 0;
#X connect 28 2 2 0;
#X connect 30 0 27 0;
#X connect 31 0 32 0;
#X connect 32 0 33 0;
#X connect 32 0 33 1;
#X connect 34 0 3 0;
#X connect 34 1 1 0;
#X connect 35 0 6 1;
#X connect 35 1 34 0;
#X connect 35 1 39 0;
#X connect 35 2 28 0;
#X connect 36 0 35 0;
#X connect 39 0 16 0;
#X connect 40 0 39 1;
#X restore 9 267 pd couchdb;
#X text 6 169 An example for a RESTful interface is CouchDB:;
#X obj 9 80 rest http://localhost:5984/;
#X text 6 114 The second outlet will output status information of the request.;
#X text 5 222 Here is a complex example for using [rest] to communicate with CouchDB. It uses GET \, POST and DELETE request methods. You will need to have a local installation of CouchDB.;
#X text 6 10 Set the base url at creation or use [init( message. An empty init message will clean a previous set base url. The number of possible parameters for [rest] and [oauth] differ. You can also use four parameters for the [init( message to use basic cookie authentication \, see below.;
#X restore 21 498 pd rest-specific;
#X text 594 369 By default correct SSL host is checked. Disable check by sending sslcheck with a value to 0 \, reenable checking by setting the value to 1;
#X msg 573 234 cancel;
#X text 628 271 Use this request to test cancelling and timeout: it will wait for 10 seconds before returning data.;
#N canvas 385 252 635 326 cancel 0;
#X obj 15 237 rest;
#X msg 115 145 cancel;
#X obj 190 106 t b b;
#X obj 190 77 bng 15 250 50 0 empty empty empty 17 7 0 10 #fcfcfc #000000 #000000;
#X msg 15 190 GET http://ix.residuum.org/pd/sleep_example.php;
#X obj 15 70 t b b;
#X obj 15 41 bng 15 250 50 0 empty empty empty 17 7 0 10 #fcfcfc #000000 #000000;
#X text 12 9 This won't always work \, as another thread will have to be signalled and must clean up.;
#X obj 97 289 print data;
#X obj 15 289 print status;
#X text 188 42 By experimentation \, I have found out that a delay of 20ms is sufficient on my system (TM).;
#X obj 187 152 del 20;
#X text 251 121 NOTE: For Windows the delay must be longer because of problems with cancelling threads from the outside \, so the object must use a different approach for cancellation.;
#X obj 97 267 spigot;
#X obj 130 241 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X connect 0 0 9 0;
#X connect 0 1 13 0;
#X connect 1 0 0 0;
#X connect 2 0 11 0;
#X connect 2 1 1 0;
#X connect 3 0 2 0;
#X connect 4 0 0 0;
#X connect 5 0 4 0;
#X connect 5 1 1 0;
#X connect 6 0 5 0;
#X connect 11 0 4 0;
#X connect 13 0 8 0;
#X connect 14 0 13 1;
#X restore 653 235 pd cancel;
#X text 628 165 You can cancel a currently executed request by issuing [cancel(. If data has been returned already \, but is not output \, or output only partially \, outputting the data will still be completed. Note \, that cancelling the call may take some time \, so do not try to issue a new request immediately. See;
#X text 19 259 [rest] is an object for communication with REST services. Request methods GET \, POST \, PUT \, DELETE \, HEAD \, OPTIONS \, PATCH and TRACE are available.;
#X text 19 455 HTTP requests are asynchronous. Do not expect a request to return data immediately. While one request is processed \, the object is blocked.;
#N canvas 358 174 423 340 download-to-file 0;
#X obj 17 237 rest;
#X text 14 10 Set the location \, where the file should be saved;
#X text 57 76 Downloaded data will write it to the file;
#X text 110 162 Clear the location;
#X msg 17 28 file /tmp/test.json;
#X msg 112 182 file;
#X obj 17 287 print done;
#X obj 101 287 print data;
#X msg 59 96 GET https://jsonplaceholder.typicode.com/posts;
#X obj 101 265 spigot;
#X obj 134 241 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X connect 0 0 6 0;
#X connect 0 1 9 0;
#X connect 4 0 0 0;
#X connect 5 0 0 0;
#X connect 8 0 0 0;
#X connect 9 0 7 0;
#X connect 10 0 9 1;
#X restore 21 578 pd download-to-file;
#X text 20 535 More functions:;
#N canvas 170 140 678 510 streaming-and-blocking 0;
#X obj 17 353 rest;
#X msg 17 142 mode stream;
#X msg 70 203 mode block;
#X text 72 182 This will reset the object to the default mode;
#X text 14 124 Setting the mode to streaming;
#X text 12 8 By default \, [rest] and [oauth] both output data only when the request has finished. Some services decide to keep an HTTP connection open and flush data to clients (streaming).;
#X text 12 59 To output that data when it is done \, use the [mode( message and set the mode to stream. The default mode is blocking mode. You can set the mode even during running requests.;
#X text 195 223 Example for a streaming webservice;
#X obj 17 433 print done;
#X obj 102 433 print data;
#X msg 197 245 GET https://ix.residuum.org/pd/stream_example.php;
#X msg 222 285 cancel;
#X obj 102 407 spigot;
#X obj 135 381 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X connect 0 0 8 0;
#X connect 0 1 12 0;
#X connect 1 0 0 0;
#X connect 2 0 0 0;
#X connect 10 0 0 0;
#X connect 11 0 0 0;
#X connect 12 0 9 0;
#X connect 13 0 12 1;
#X restore 21 600 pd streaming-and-blocking;
#N canvas 114 149 628 451 setting-headers 0;
#X obj 76 327 rest;
#X msg 191 226 GET https://api.github.com/repos/residuum/PuRestJson/contents/Makefile;
#X msg 74 62 header Accept: application/json;
#X msg 126 110 header User-Agent: My User Agent;
#X text 71 0 You can set arbitrary HTTP headers with the [header( message.;
#X text 180 155 To clear HTTP headers \, issue [header_clear(;
#X msg 182 172 header_clear;
#X text 71 32 Some webservices return different data types for different values of Accept: headers;
#X obj 158 389 print data;
#X obj 76 389 print done;
#X obj 238 389 print error;
#X text 125 90 Github requires User-Agent: header;
#X obj 158 367 spigot;
#X obj 191 341 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X connect 0 0 9 0;
#X connect 0 1 12 0;
#X connect 0 2 10 0;
#X connect 1 0 0 0;
#X connect 2 0 0 0;
#X connect 3 0 0 0;
#X connect 6 0 0 0;
#X connect 12 0 8 0;
#X connect 13 0 12 1;
#X restore 21 556 pd setting-headers;
#N canvas 696 177 899 593 proxy 0;
#X obj 291 442 rest;
#X msg 433 380 proxy;
#X text 460 46 This request returns the IP address of the connected computer;
#X text 433 219 You must always specify protocol \, server and port number.;
#X text 433 239 If your proxy needs a username and password \, add those delimited by spaces \, like;
#X msg 436 276 proxy protocol://server:port username password;
#X text 431 342 To clear proxy settings \, send a proxy message without any parameter to the object.;
#X msg 460 78 GET https://ix.residuum.org/pd/proxy_example.php;
#X msg 328 206 cancel;
#X obj 301 486 spigot;
#X obj 334 460 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X obj 301 509 print;
#X msg 58 188 proxy socks5://192.252.208.67:14287;
#X msg 37 248 proxy socks4://161.97.169.216:1080;
#X msg 125 142 proxy https://135.181.103.249:8888;
#X text 34 49 WARNING: all those proxies are from some dubious lists on the internet \, use at your own risk. These may not be up during the test.;
#X msg 62 114 proxy http://47.89.185.178:8888;
#X obj 455 486 print error;
#X text 34 356 Running TOR locally in standard configuration, f 23;
#X msg 35 388 proxy socks5://127.0.0.1:9050;
#X connect 0 1 9 0;
#X connect 0 2 17 0;
#X connect 1 0 0 0;
#X connect 7 0 0 0;
#X connect 8 0 0 0;
#X connect 9 0 11 0;
#X connect 10 0 9 1;
#X connect 12 0 0 0;
#X connect 13 0 0 0;
#X connect 14 0 0 0;
#X connect 16 0 0 0;
#X connect 19 0 0 0;
#X restore 21 622 pd proxy;
#X obj 623 576 print error;
#X obj 450 576 print done;
#X obj 529 577 print data;
#X msg 628 304 GET https://ix.residuum.org/pd/sleep_example.php;
#X msg 451 32 GET https://jsonplaceholder.typicode.com/posts;
#X text 19 349 All requests are issued with [REQUEST_METHOD URL DATA( where REQUEST_METHOD is the uppercase verb of the method \, URL is the request URL \, or the relative server path \, if [url( or initialization is used \, and DATA is the upload data for PUT or post data for POST. For creating url encoded lists of parameters see;
#X text 19 302 [oauth] is an object for communication with OAUTH enabled webservices. Request methods GET \, POST \, PUT \, DELETE \, HEAD \, OPTIONS and TRACE are available.;
#X obj 21 668 declare -path purest_json;
#X text 18 90 To mitigate that \, set the [spigot]s only to 1 \, if running Pd with the command line switch -stderr \, that will redirect the output to the command line instead of the Pd console.;
#X obj 529 555 spigot;
#X obj 562 531 tgl 18 0 empty empty empty 0 -9 0 10 #fcfcfc #000000 #000000 0 1;
#X text 18 132 Another strategy can be to use [text] for storing data for inspection.;
#X text 18 9 WARNING: [print]ing downloaded data to console may lead to undesired behaviour \, because it usually contains special characters such as curly braces \, backslashes \, or quotation marks that may be interpreted as tcl commands and therefore break the console or even crash Pd. Data from arbitrary URLs can also contain malicious data.;
#X obj 409 671 text define \$0-example;
#X obj 519 619 text insert \$0-example;
#X connect 2 0 27 0;
#X connect 2 1 35 0;
#X connect 2 1 40 0;
#X connect 2 2 26 0;
#X connect 4 0 2 0;
#X connect 5 0 2 0;
#X connect 6 0 2 0;
#X connect 7 0 2 0;
#X connect 15 0 2 0;
#X connect 29 0 2 0;
#X connect 30 0 2 0;
#X connect 35 0 28 0;
#X connect 36 0 35 1;