APIFunction   
Copy to clipboard.

✖
`APIFunction`

✖

APIFunction[{"name₁"type₁,"name₂"type₂,…},fun]

represents an API with parameters name_i that evaluates the function fun whenever it is called. The function fun is applied to "name₁"val₁,"name₂"val₂,…, where the val_i are the settings for the parameters, interpreted as being of types type_i.

✖

APIFunction[{"name₁"type₁default₁,…},fun]

takes the value of the parameter name_i to be default_i if it is not specified when the API is called.

✖

APIFunction[params,fun,fmt]

specifies that the result from applying fun should be returned in format fmt.

✖

APIFunction[params,fun,{fmt,rform}]

specifies that the result should be returned as a response of the form rform.

✖

APIFunction[params,fun,{fmt,rform,failfmt}]

specifies that in the event of failure, the result should be returned in format failfmt.

Details and Options

CloudDeploy[APIFunction[…]] deploys an API function so that it can be called externally in the cloud using a web GET request, as from a web browser, or a POST request.
APIFunction takes a parameter setting name_i=str_i in a web query string or POST request and converts it to an element "name_i"->Interpreter[type_i]["str_i"] in the association to which fun is applied.
Within the Wolfram Language, APIFunction[…][assoc] can be used to reproduce the effect of calling the API function with the parameter settings given in assoc. In this case, if any of the settings are not strings, their values are used directly, without type interpretation.
Possible forms of type_i specifications are:

	"form"	any form supported by Interpreter
	Restricted[…], etc.	any restricted form etc. supported by Interpreter
	Interpreter[…]	any Interpreter object
	assoc	an association giving details of how to treat the parameter
	tfun	any function to be applied to the string

Possible elements in the association include:

	"Interpreter"	the interpreter to be used for this parameter
	"Required"	whether this parameter is required
	"Default"	a default value, if any, for the parameter
	"AllowedExtensions"	extensions to allow for this parameter
	"Help"	help to associate with the parameter

The default for "AllowedExtensions" is Inherited, corresponding to allowing extensions as specified in the setting for the APIFunction option AllowedCloudParameterExtensions.
When called in the cloud, APIFunction[params,fun] by default returns a textual Wolfram Language form of the result.
Possible result formats fmt in APIFunction[params,fun,fmt] are:
"fmt" any format supported by ExportForm

f an arbitrary function to be applied to body
APIFunction[params,fun,"fmt"] is equivalent to APIFunction[params,ExportForm[fun[#],"fmt"]&] when deployed. Note that ExportForm will not appear when evaluating APIFunction in a notebook.
Typical possible result formats include:

	None	pure Wolfram Language text (default)
	"GIF","JPEG","PNG",…	an image of the result
	"String"	a string result as a raw string
	"HTML"	pure static HTML version of the result
	"HTMLThemed"	static HTML with built-in theme
	"HTMLPaneled"	HTML content in a panel

APIFunction supports the following options:

AllowedCloudExtraParameters	None	what extra parameters to allow for the API
AllowedCloudParameterExtensions	Automatic	what extensions to allow for parameters
ImageFormattingWidth	Automatic	wrapping width for output formatting
ImageSize	Automatic	overall image size for output

APIFunction[params,fun,{"fmt","rform"}] is equivalent to APIFunction[params,ResponseForm[ExportForm[fun[#],"fmt"],"rform"]&] when deployed. Note that neither ResponseForm nor ExportForm will appear when evaluating APIFunction in a notebook.
If the parameters are not successfully interpreted, fun is not applied, and instead the returned result is Failure["src",<|fname₁->Failure[…],fname₂->Failure[…]|>], where the fname_i are names of parameters whose interpretation failed.
If a parameter with no default value is missing, Failure["MissingParameter",…] is generated.
If rform is specified, the Failure[…] expression is passed directly to the response form, whether or not fmt is specified.
When an API defined by APIFunction[…] is called through the web, an HTTP status code of 200 is returned if the parameters are successfully interpreted, and the result of applying fun is not Failure[…]. Otherwise a status code of 400 is returned.
In APIFunction[params,…], the params can be a FormObject or other form used as a form specification in FormFunction. Features of the form specification not relevant to the API are ignored. APIFunction allows the same options as FormFunction but ignores those that do not apply.
In APIFunction[…,fmt] or in APIFunction[…{fmt₁,…}], any of the fmt expressions can be given as either a string format or as a list of the form {"fmt",optname₁optvalue₁,…}, where the optname_i are the options for the "fmt" format.

Examples

open allclose all

Basic Examples (4)Summary of the most common use cases

An API function with one parameter named x applied to an Association:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-1tpebo

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-zaqccp

Out[2]=2

An API function with an optional parameter having a default value:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-g7w27f

Out[1]=1

Use CloudDeploy to deploy an API function to the Wolfram Cloud:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-hzus0j

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-bkwd5e

Out[2]=2

The deployed API function can be invoked by accessing the cloud object in a web browser and appending ?x=value to its URL:

Calling an APIFunction with insufficient input data will return a Failure:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-zuy9ff

Out[1]=1

Scope (6)Survey of the scope of standard use cases

An API function that returns the result of the computation as Wolfram Language text inside a JSON container with metainformation about the computation:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-0xvh33

Out[1]=1

Interpreter Specifications (1)

Use rich Interpreter specifications:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-fv3l5m

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-fd52up

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0cg44uf7m-zxd9kc

Out[3]=3

A list can be used to create a choice list:

In[4]:=4

✖

https://wolfram.com/xid/0cg44uf7m-6smtp1

Out[4]=4

In[5]:=5

✖

https://wolfram.com/xid/0cg44uf7m-fea60o

Out[5]=5

In[6]:=6

✖

https://wolfram.com/xid/0cg44uf7m-5bqztx

Out[6]=6

Defaults (4)

Specify a default for a field; fields that have a default are not required:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-cdiz5z

Out[1]=1

Fields can be optional without having a default:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-b016u0

Out[1]=1

Use the default specification to allow for empty strings:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-wg24w3

Out[1]=1

Use RuleDelayed to evaluate a new default every time:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-y9e2f2

Out[1]=1

Options (3)Common values & functionality for each option

AllowedCloudExtraParameters (1)

Allow the caller of an APIFunction to set the format used for exporting the result:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-ljpfdw

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-pd5wfk

Out[2]=2

If the "_exportform" parameter is not specified in the call, the APIFunction will not export the result:

In[3]:=3

✖

https://wolfram.com/xid/0cg44uf7m-1kri1b

Out[3]=3

AllowedCloudParameterExtensions (2)

Deploy an APIFunction that accepts JSON encoded matrices:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-56aeyp

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-gdyye0

Out[2]=2

Deploy an APIFunction that accepts parameters given as Wolfram Language data:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-mqmro7

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-jsvn1s

Out[2]=2

Applications (7)Sample problems that can be solved with this function

Get a map of any country:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-2wmqil

Out[1]=1

Find the latest stock price for a given symbol:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-pavtx0

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-fva45q

Out[2]=2

Plot a CellularAutomaton:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-75cn3a

Out[1]=1

Deploy a BarChart API:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-mi3enk

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-cmobo6

Out[2]=2

Deploy an API to create and redirect to a new FormFunction:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-5yrnex

Out[1]=1

Deploy an API to get the population for any country in a given year:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-vjvy73

Out[1]=1

Return a full webpage from a template:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-z45kl7

Out[1]=1

Properties & Relations (9)Properties of the function, and connections to other functions

A deployed API can be accessed from any HTTP client (given proper authentication if required):

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-sp8fvo

Out[1]=1

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-bouxn8

Out[2]=2

In[3]:=3

✖

https://wolfram.com/xid/0cg44uf7m-ev48rc

Out[3]=3

APIFunction is designed to be interchangeable with FormFunction:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-uunrde

Out[1]=1

And vice versa:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-lxs0m4

Out[1]=1

APIFunction accepts the same options as FormFunction but ignores most of them:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-7ckdbq

Out[1]=1

The single fields of an APIFunction use Interpreter to transform the input in Wolfram Language expressions:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-pwx7ot

Out[1]=1

This is effectively the same as the following:

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-me9ej6

Out[2]=2

And the same as applying Interpreter directly:

In[3]:=3

✖

https://wolfram.com/xid/0cg44uf7m-02zt3a

Out[3]=3

An APIFunction is executed with $EvaluationEnvironment set to "WebAPI" and with $CloudEvaluation being True:

In[1]:=1

✖

https://wolfram.com/xid/0cg44uf7m-wcivjs

Out[1]=1

Compare this to the result in a desktop session:

In[2]:=2

✖

https://wolfram.com/xid/0cg44uf7m-ff1en3

Out[2]=2

The evaluation environment for CloudEvaluate is "WebEvaluation":

In[3]:=3

✖

https://wolfram.com/xid/0cg44uf7m-eqatnm

Out[3]=3

APIFunction is useful to perform computations on demand based on input parameters. For computations that do not depend on any input parameters, Delayed can be used as well:

In[1]:=1