Appendix: URL conventions

This section describes how the Dynamic API parses the URL you provide for calling the Dynamic API built-in endpoints or user-defined QuickApps.

Table 1. Interacting with 1010 paths
Syntax Description Examples
/api Invoke /api/index, running default.api.index /api
/api/[e] Invoke standard endpoint default.api.[e] /api/sql

/api/ls
/api/[e.p] If [e.p] is a directory, invoke/api/ls/[e.p]. If you are in a top level directory, use api/ls/dir to resolve the ambiguity between this and a standard endpoint (default.api.[e]).

If [e.p] is a table or query, return the resulting data.

If [e.p] is a library, invoke /api/defs/[e.p]. If [e.p] has a query at the bottom, including dynamic queries, that will be run instead.

If [e.p] is a QuickApp, run the QuickApp. If the QuickApp has a widget named index, return the data from that widget. Otherwise, return a table of widgets. (You should probably first use /api/new/[e.p] to obtain a new tag.)

 /api/pub.demo.weather

/api/pub.demo.weather.stations
Table 2. Interacting with QuickApps that don't contain a widget named "index"
Syntax Description Examples
/api/[e] Fetch dynamic status table for endpoint [e] /api/path.to.quickapp
/api/[e]/[y] Fetch widget [y] for endpoint [e]. Since there is no index widget, Dynamic API will treat [y] as a widget name. /api/path.to.quickapp/widget_name
Table 3. Interacting with QuickApps that do contain a widget named "index"
Syntax Description Examples
/api/[e] Render or return the value of the widget named index /api/ls (the index widget is called by default)
/api/[e]/[y] Set variable named path equal to [y] and render or return the value of the widget named index. [y] must not begin with a period (.) The Dynamic API will automatically resolve to any widget named index, so no reference to a widget name in the path is necessary. /api/ls/directory.subdirectory
api/[e]/.[w] Render or return the value of the widget named [w]. The period (.) tells the Dynamic API to treat [w] as a widget instead of something to set in the path variable. Since Dynamic API automatically resolves to any widget named index, you must override this behavior using the .[w] syntax. /api/path.to.quickapp/.widget_name
api/[e]/@ Explicitly requests the widget status table when [e] contains an index widget. /api/path.to.quickapp/@
Table 4. Calling widget methods
Syntax Description Examples
/api/[e]!methods List methods available for a widget. Each widget has its own list of supported methods, and users can implement their own methods by writing custom widgets. [e] must resolve to a widget, either by being of the form path.to.quickapp/widget_name or by specifying a QuickApp with a widget named index. /api/path.to.quickapp/my_grid_widget!methods
/api/[e]/.[w]![m] Invoke method [m] on widget [w] for QuickApp [e]. These methods are defined per the widget class you are using. !data, !cols, !rows, !head
/api/![m] Invoke root-level method [m] /api/!login

/api/!logout
Table 5. Setting variables in QuickApps
Syntax Description Examples
/api/[e]?[y]=[z]&[a]=[b] Sets dynamic variable @y to value z and @a to value. You can also set variables in the body of the POST request. /api/path.to.quickapp?date=20200101&state=NY
/api/[e]?_[y]=[z](There is a leading _ in variable name) Sets special system "variables" available to the QuickApp. For example, _fmt is a system variable that determines the format of the output from the Dynamic API. _fmt=json
/api/[e]?[x]_=[y] (There is a trailing _ in variable name) Sets parameters for widget methods. For example, for the data method, calling /api/[e]!data?range_=1&to_=10 calls data(range=2, to=10) for widget [e]. range_, to_
Table 6. Changing output format
Syntax Description Examples
/api/[e]:[f]

You can also use the alternate format as follows: /api/[e]?_fmt=[f]

 Render output in format [f]. The default format is html. [f] is an alias for setting the system variable _fmt=[f].

The format goes before the URL query, for example: /api/[e]:[f]?[a]=[b]

 :html, :text, :json, :json.keyed

Alternatively, _fmt=json, _fmt=text