APIFunction
This feature relies on access to Wolfram Cloud.

APIFunction[{"name1"type1,"name2"type2,},fun]
represents an API with parameters that evaluates the function fun whenever it is called. The function fun is applied to , where the are the settings for the parameters, interpreted as being of types .

APIFunction[{"name1"type1default1,},fun]
takes the value of the parameter to be 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 result should be returned as a response of the form rform.

DetailsDetails

  • CloudDeploy[APIFunction[]] deploys an API function so that it can be called externally in the cloud, typically using a RESTful interface.
  • APIFunction takes a parameter setting 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 type specifications are:
  • "form"any form supported by Interpreter
    Restricted[], etc.any restricted form etc. supported by Interpreter
    Interpreter[]any Interpreter object
    tfunany function to be applied to the string
  • 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 HTML version of the result
    "CloudCDF"CloudCDF with interactive components in the cloud
    "HTMLCloudCDF"pure HTML with CloudCDF if needed
    "JSON"JSON representation of the result
  • APIFunction supports the following options:
  • 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"]&], so 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 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.

ExamplesExamplesopen allclose all

Basic Examples  (4)Basic Examples  (4)

An API function with one parameter named 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]=
Introduced in 2014
(10.0)