APIFunction   

Listing of Parameter Types »

APIFunction[{"name1"type1,"name2"type2,…},fun]

represents an API with parameters namei that evaluates the function fun whenever it is called. The function fun is applied to "name1"val1,"name2"val2,…, where the vali are the settings for the parameters, interpreted as being of types typei.

APIFunction[{"name1"type1default1,…},fun]

takes the value of the parameter namei to be defaulti 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 namei=stri in a web query string or POST request and converts it to an element "namei"->Interpreter[typei]["stri"] 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 typei specifications are:
  • "form"any form supported by Interpreter
    Restricted[…], etc.any restricted form etc. supported by Interpreter
    Interpreter[…]any Interpreter object
    assocan association giving details of how to treat the parameter
    tfunany 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
    fan 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:
  • Nonepure 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 Nonewhat extra parameters to allow for the API
    AllowedCloudParameterExtensions Automaticwhat extensions to allow for parameters
    ImageFormattingWidthAutomaticwrapping width for output formatting
    ImageSizeAutomaticoverall 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",<|fname1->Failure[…],fname2->Failure[…]|>], where the fnamei 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[…{fmt1,…}], any of the fmt expressions can be given as either a string format or as a list of the form {"fmt",optname1optvalue1,…}, where the optnamei are the options for the "fmt" format.

Examples

open allclose all

Basic Examples  (4)

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

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

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

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:

Scope  (6)

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

Interpreter Specifications  (1)

Use rich Interpreter specifications:

A list can be used to create a choice list:

Defaults  (4)

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

Fields can be optional without having a default:

Use the default specification to allow for empty strings:

Use RuleDelayed to evaluate a new default every time:

Options  (3)

AllowedCloudExtraParameters  (1)

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

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

AllowedCloudParameterExtensions  (2)

Deploy an APIFunction that accepts JSON encoded matrices:

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

Applications  (7)

Get a map of any country:

Find the latest stock price for a given symbol:

Plot a CellularAutomaton:

Deploy a BarChart API:

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

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

Return a full webpage from a template:

Properties & Relations  (9)

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

APIFunction is designed to be interchangeable with FormFunction:

And vice versa:

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

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

This is effectively the same as the following:

And the same as applying Interpreter directly:

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

Compare this to the result in a desktop session:

The evaluation environment for CloudEvaluate is "WebEvaluation":

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:

Equivalent code that uses APIFunction:

The result of $CloudEvaluation is True for both executing an API function and using CloudEvaluate:

With the default setting IncludeDefinitionsTrue, deploying an API function includes all definitions it depends on:

Possible Issues  (3)

Export and response formats are only applied when the API is executed on the web:

When manually building a query to an APIFunction, it is important to apply URLEncode to it:

Note that calling URLExecute with a list of rules will automatically encode the query parameters:

Multiple requests to the same APIFunction are not typically evaluated in the same Wolfram Engine, hence definitions do not persist between requests:

Wolfram Research (2014), APIFunction, Wolfram Language function, https://reference.wolfram.com/language/ref/APIFunction.html (updated 2017).

Text

Wolfram Research (2014), APIFunction, Wolfram Language function, https://reference.wolfram.com/language/ref/APIFunction.html (updated 2017).

CMS

Wolfram Language. 2014. "APIFunction." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2017. https://reference.wolfram.com/language/ref/APIFunction.html.

APA

Wolfram Language. (2014). APIFunction. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/APIFunction.html

BibTeX

@misc{reference.wolfram_2024_apifunction, author="Wolfram Research", title="{APIFunction}", year="2017", howpublished="\url{https://reference.wolfram.com/language/ref/APIFunction.html}", note=[Accessed: 22-December-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_apifunction, organization={Wolfram Research}, title={APIFunction}, year={2017}, url={https://reference.wolfram.com/language/ref/APIFunction.html}, note=[Accessed: 22-December-2024 ]}