APIFunction

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"]&].
  • 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
    "HTMLCloudCDF"pure HTML with cloud CDF if needed
    "CloudCDF"CDF with interactive components in the cloud
    "CloudCDFElement"embeddable interactive CDF element in the cloud
  • APIFunction supports the following options:
  • AllowedCloudExtraParametersNonewhat extra parameters to allow for the API
    AllowedCloudParameterExtensionsAutomaticwhat 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"]&], as long as the parameters are successfully interpreted.
  • 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.

Examples

open allclose all

Basic Examples  (4)

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

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

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

In[1]:=
Click for copyable input
Out[1]=

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

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

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

An APIFunction that has insufficient data will return a Failure:

In[1]:=
Click for copyable input
Out[1]=

Scope  (6)

Options  (3)

Applications  (7)

Properties & Relations  (5)

Possible Issues  (2)

See Also

FormFunction  CloudDeploy  EmbedCode  ExportForm  ResponseForm  HTTPResponse  Delayed  ExternalBundle  URLDispatcher  MailReceiverFunction  Function

Introduced in 2014
(10.0)