fetch(urlStr,headersDict,attrNameStr,cmdStr[,httpMethod,POSTbody])

---

fetch(urlStr,headersDict,attrNameStr,cmdStr[,httpMethod,POSTbody])

The fetch() operator enables collecting data from a server when greater flexibility than when using AutoFetch. For most purposes, AutoFetch should be the primary choice;> If uncertain use AutoFetch unless it proves not to work; fetch() is an advanced operator for the few who need it.

urlStr is the URL source to be called into Tinderbox.

headersDict is a dictionary of HTTP(S) headers. This must be an empty dictionary {} (no enclosing quotes) if you do not need custom headers.

attrNameStr is the name of (not a reference to) an attribute or local variable in which the output of the fetch process is stored. Note the difference from AutoFetch which places the output directly into $Text. Here, the data from the remote server will be fetched asynchronously, and stored in this attribute or local variable. Note that this parameter is not evaluated, i.e. "MyString" not $MyString, unless attribute MyString hold the name of an attribute. This attribute cannot be left empty and must be a literal quoted string, an attribute reference or a variable.

cmdStr is a Tinderbox action expression (or semi-colon delimited sequence of actions) to be performed after the data is fetched; i.e. the value is action code. Be aware that the latter may be some time after the fetch operator returns; do not assume full processing happens immediately. It may be an empty string "" if no transform is needed on the recovered data (this in unlikely to be the case).

httpMethod is an optional argument, indicating the HTTP request method to be used. HTTP 1.1. defined methods (per RFC 9110) are GET, HEAD, POST , PUT (including PATCH), DELETE, CONNECT, OPTIONS, and TRACE. If httpMethod is not specified, fetch() defaults to using a GET request. The methods allowed are as per the HTP protocol in use at the server, rather than a restriction by Tinderbox. Also be aware that support for a given method may also be a constraint at the server end of the request.

POSTbody is an optional argument. If the httpMethod is POST, POSTbody specifies a message body to be sent to the designated server.

Note that the server might take several seconds or more before supplying a response. fetch() returns immediately without waiting for the server, and arranges for the command to be evaluated when the data arrive; Tinderbox will continue to try for c.30 seconds before giving up. Why? Because Tinderbox has no control over the time the source at urlStr takes to return the requested data.

Given this possible delay between calling fetch() and the completion of the full process, it may be necessary to take steps to avoid repeating the fetch() call before the previous operation has completed. For example, this can be done by setting a $MyBoolean(/In Progress) to true immediately before starting the fetch, and setting it to false when all is complete. Note: the choice of an "In Progress" note to hold the boolean is just one approach—where the boolean value is stored and in which attribute are choices for the user to make.

fetch() processes its command on a serial queue. So, if several fetch() requests are outstanding, they will not interfere: that queue is the sequence in which they will be evaluated.

The show() operator can be used as part of the cmdStr, as a way of giving feedback.

Examples

Suppose there is a need to interact with an API. Typically, that means:

• Passing a GET or POST message to a designated URL.
  • Possibly doing this using some custom headers for authentication or other reasons.
• Wait for the server to respond.
• When the server does respond, take what is returned and process it.

Note how this is more complex than previous AutoFetch. But, custom headers may be needed or it may be necessary to process the results right away. For example, the result might say: "Here are the first ten results; and here is a magic token to send to get the next ten." Such tokens are typically good for a short time only. AutoFetch was not designed for such complications.

In the following example, notice the fetch() argument #2 uses the newer {} style of dictionary declaration:

 var string aServerULR = "https://yourserver.com";
	var string myPayload = "?status=publish";
	
	fetch(aServerULR + myPayload,{Content-Type: application/json},"aTempVariable","doProcessCallback(aTempVariable);",POST)
	
	function doProcessCallback(returnValue:string) {
   		show(returnValue);
	};

Here is a fuller example of a Readwise data importer function as an example. Be aware that the code refers to user fuctions, e.g. 'rwHeaders()' that are not included in the example code:

function getHighlights(auth:string,page:string) {
	rwSetup();
	if(rwIsInProgress()) {
		show("Readwise already in progress");
		return;
		}

	show("Readwise starting import");
	rwMarkInProgress();

	var:string theLog=create("/log");
	fetch(rwURL(page),rwHeaders(auth),"temp","rwParse(temp,/log,0)");

	}

Note: everything in the above example with an 'rw' prefix is a function.