Extension:WikiLambda/API

The WikiLambda extension has a simple API for internal and external use. These APIs let you search and fetch WikiFunctions content and retrieve it in different formats and after different transformations.

These APIs are modules and submodules of MediaWiki Action API. You can make requests, explore the examples and see the results in the MediaWiki API Sandbox.

wikilambda_fetch
This API allows to retrieve one or more of ZObject pages from Wikifunctions. Every requested ZObject will be returned as a string encoding its canonical JSON representation. If a particular language is requested, the ZObject will return its root object label in the selected language (or fallbacks).

This API, designed as an Action API module, is created for its external use and hence the returned ZObjects are encoded as strings. For internal use in the Wikifunctions application, please see below the documentation of

Documentation
Method: GET

Action: wikilambda_fetch

Request: api.php?action=wikilambda_fetch&format=json&zids=Z111|Z112&language=en

Response:

Possible Errors
This API expects no errors to be found. If any of the ZIDs is invalid or cannot be found, the returned object will consist solely on the found error and will not return the valid objects.

Examples

 * api.php?action=wikilambda_fetch&format=json&zids=Z1
 * Returns the canonical representation of the ZObject with ZID  with its labels in all available languages.


 * api.php?action=wikilambda_fetch&format=json&zids=Z1|Z2|Z3
 * Returns the canonical representation of the ZObjects with ZIDs,   and   with its labels in all available languages.


 * api.php?action=wikilambda_fetch&format=json&zids=Z4|Z6&language=es
 * Returns the canonical representation of the ZObjects with ZIDs  and   with its root-level label in Spanish or available fallback languages.

wikilambda_edit
This API allows to create/edit persisted ZObject pages in Wikifunctions. The API expects the parameter  to be a valid JSON representation of the ZObject in its canonical form.

To create a new ZObject, the parameter  must be omitted, and Wikifunctions will find and assign the next available ZID. Also, the keys from the JSON ZObject that refer to its identity (for example,  or the values of   and  ), must be set to the Null Reference.

To edit an existing ZObject, the parameter  must have the ZID of the ZObject to edit (which will be the same one as the internal identity keys).

Documentation
Method: GET

Action: wikilambda_edit

Request: api.php?action=wikilambda_edit&format=json&summary=TestSummary&zid=Z10001&zobject=

Response:

Possible Errors
This API can return a wide variety of errors, because the provided ZObject is parsed and validated against the canonical schemata. All the validation errors will be wrapped in a error of type. Apart from the validation errors, Wikifunctions can detect a variety of problems described below.

Examples

 * api.php?action=wikilambda_edit&format=json&summary=New zobject&zobject=urlencode( ZOBJECT )&token=%2B\
 * Where ZOBJECT is:
 * Creates and saves a new ZObject in the database (empty values) and returns the newly assigned ZID.
 * Creates and saves a new ZObject in the database (empty values) and returns the newly assigned ZID.


 * api.php?action=wikilambda_edit&format=json&summary=Edit zobject&zid=Z10004&zobject=urlencode( ZOBJECT )&token=%2B\
 * Where ZOBJECT is:
 * Edits the ZObject with title Z10004 and overwrites it with the given JSON ZObject.
 * Edits the ZObject with title Z10004 and overwrites it with the given JSON ZObject.

wikilambda_function_call
One of the entrypoints to the Wikifunctions orchestration and evaluation back-end. This API receives a required JSON formatted ZObject and sends it to the function-orchestrator services for it to be evaluated and returned. Hence, the ZObject sent must be a Z7/Function call.

Documentation
Method: GET

Action: wikilambda_function_call

Request: api.php?action=wikilambda_function_call&format=json&wikilambda_function_call_zobject=

Response:

Possible Errors
Describe function-orchestrator and evaluator most probable errors

Examples

 * api.php?action=wikilambda_function_call&format=json&wikilambda_function_call_zobject=
 * Where the function is:
 * Requests the execution of the function with ZID Z802 (built-in function ), where the value of   is  . The expected result is to be returned the value of  . The returned result, as expected:
 * Observe what happens when, instead of passing  as the condition, we pass  :
 * Observe what happens when, instead of passing  as the condition, we pass  :
 * Observe what happens when, instead of passing  as the condition, we pass  :

wikilambda_perform_test
Endpoint to query test results for a ZFunction. Accepts a, a list of  , and a list of. Accepts a ZID for the ZFunction, and a list of either ZIDs or full JSON ZObjects for the ZImplementations and ZTesters.

If a test result is up-to-date in the results database cache, it will be retrieved from there. Otherwise, the test will be run by a call to the WikiFunctions orchestrator.

In addition, under certain conditions this API reorders the implementations of the given function and updates the function's  property in persistent storage. The reordering indicates increasing average execution times of the orchestrator (and possibly other backend services) in running the ZTesters. Reordering only involves the function's currently attached ZImplementations and ZTesters. For reordering to occur, the requested ZImplementations / ZTesters must either be blank or a superset of currently attached ZImplementations / ZTesters, and there must be no results retrieved from the cache.

Documentation
Method: GET

Action: wikilambda_perform_test

Request: api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_zimplementations=Z913& wikilambda_perform_test_ztesters=Z8130

Response:

Possible Errors
If an error occurs when evaluating a given ZTester's Z20K2, this error will be found in the "errors" entry of the returned "testMetadata". The error may be of any sort returned by. If an error occurs when evaluating Z20K3, this will be found in the "validateErrors" entry.

Other errors this API method may return:

Examples

 * api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_zimplementations=Z913&wikilambda_perform_test_ztesters=Z8130
 * Requests running ZTester Z8130 on ZFunction Z813, with Z813 implemented by ZImplementation Z913.


 * api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_zimplementations=Z913
 * Requests running all available ZTesters for ZFunction Z813, with Z813 implemented by Z913.


 * api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_ztesters=Z8130
 * Requests running ZTester Z8130 on ZFunction Z813, with Z813 implemented by each of its available ZImplementations in turn.


 * api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_zimplementations=&wikilambda_perform_test_ztesters=Z8130
 * Requests running ZTester Z8130 on ZFunction Z813, with Z813 implemented by the ZImplementation encoded in URL_ENCODED_JSON_ZIMPLEMENTATION. Where URL_ENCODED_JSON_ZIMPLEMENTATION is


 * api.php?action=wikilambda_perform_test&format=json&wikilambda_perform_test_zfunction=Z813&wikilambda_perform_test_zimplementations=Z913&wikilambda_perform_test_ztesters=
 * Requests running the ZTester encoded in URL_ENCODED_JSON_ZTESTER on ZFunction Z813, with Z813 implemented by ZImplementation Z913. Where URL_ENCODED_JSON_ZTESTER is:

wikilambdaload_zobjects
Similarly to the  API detailed below, this API returns an aggregation of ZObject pages from Wikifunctions. This API is a list submodule of the  action=query API and is dedicated to extension-wide internal requests. The return format is an array with the valid JSON representation of the ZObjects requested. It provides different parameters to configure the type of format to serialize the ZObjects to (either normal or canonical form) and the language for the object labels.

Documentation
Method: GET

Action: query

List: wikilambdaload_zobjects

Request: api.php?action=query&format=json&list=wikilambdaload_zobjects&wikilambdaload_zids=Z111|Z112&wikilambdaload_language=en&wikilambdaload_canonical=1

Response:

Possible Errors
Unlike the wikilambda_fetch API, this API can handle errors while still returning the information of the ZObjects that have been found. The returned errors will also be ZObjects of type ZError (Z5). To distinguish between the return of an error in the API execution and the return of a requested ZError object, the response includes the value `success` for each of the requested `ZIDs`.

The possible errors that can be returned for an individual ZID are detailed below.

Examples

 * api.php?action=query&format=json&list=wikilambdaload_zobjects&wikilambdaload_zids=Z1|Z2
 * Returns the normal JSON representation of the ZObjects with ZID  and   with its labels in all available languages.


 * api.php?action=query&format=json&list=wikilambdaload_zobjects&wikilambdaload_zids=Z3|Z4&wikilambdaload_language=ay
 * Returns the normal JSON representation of the ZObjects with ZIDs  and   with all its ZMultilingual String (Z12) objects filtered to only return Aymaran labels. If an Aymaran label is not found, it will return those in any of the available fallback languages.


 * api.php?action=query&format=json&list=wikilambdaload_zobjects&wikilambdaload_zids=Z6&wikilambdaload_canonical=1
 * Returns the canonical representation of the ZObjects with ZID.

wikilambdasearch_labels
This API query list generator lets you search ZObjects by their labels or aliases in a given language. It also provides a series of parameters that allow to filter by the ZObject type or by the return type of existing ZFunctions. It principally exists to support the look-ahead search system, and it's generally used in the front-end components that allow the user to search and select persisted ZObjects.

Documentation
Method: GET

Action: query

List: wikilambdasearch_labels

Request: api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_search=foo&wikilambdasearch_language=eu&wikilambdasearch_type=Z4&wikilambdasearch_return_type=Z4&wikilambdasearch_strict_return_type=true

Response:

Possible Errors
None. When nothing is found it will return an empty list.

Examples

 * api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_search=ThisLabelDoesNotExist&wikilambdasearch_language=en
 * No labels in English match or contain the substring ThisLabelDoesNotExist, so an empty batch is returned.


 * api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_search=TEX&wikilambdasearch_language=en
 * Return every label matching or containing the substring TEX in English. This might ensure that at least two builtin ZObjects will be returned: Z12 "Multilingual text" and Z11 "Monolingual text".


 * api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_search=TEX&wikilambdasearch_language=en&wikilambdasearch_exact=1
 * Return every label matching or containing the exact substring TEX in English. This will not return the two ZObjects returned in the previous example, as this search is case-sensitive.


 * api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_language=en&wikilambdasearch_return_type=Z40
 * Return the English label of every entry that has a ZBoolean (Z40) return type, including those that have a generic ZObject (Z1) return type.


 * api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_language=en&wikilambdasearch_return_type=Z40&wikilambdasearch_strict_return_type=true
 * Return the English label of every entry that has strictly a ZBoolean (Z40) return type.

wikilambdafn_search
This API query list searches for the IDs of all ZObjects associated with a provided  ZID and that belong to a given type (either   or  ).

Documentation
Method: GET

Action: query

List: wikilambdafn_search

Request: api.php?action=query&format=json&list=wikilambdafn_search&wikilambdafn_zfunction_id=Z801&wikilambdafn_type=Z20

Response:

Possible Errors
None. When nothing is found it will return an empty list.

Examples

 * api.php?action=query&format=json&list=wikilambdafn_search&wikilambdafn_zfunction_id=Z801&wikilambdafn_type=Z20
 * Returns the list of Z20/Testers associated to the function with ZID Z801


 * api.php?action=query&format=json&list=wikilambdafn_search&wikilambdafn_zfunction_id=Z801&wikilambdafn_type=Z14
 * Returns the list of Z14/Implementations associated to the function with ZID Z801

wikilambda_health_check
This is an internal API for performing health check against the wikilambda + function orchestrator + function evaluator interface. It performs a few example function calls against the orchestrator and checks the response against the expected outcomes. It takes no argument.

We have set up a prometheus blackbox probe that calls this API every 15 seconds to confirm the liveliness and correctness of our services. Beware that currently (Aug 2022) this endpoint can return failed results due to flakiness in the orchestrator (possibly due to load capacity).

Documentation
Method: GET

Action: wikilambda_health_check

Request: api.php?action=wikilambda_health_check

Response:

Possible outcomes

 * Successful
 * success = "true"
 * total_tests = tested = passed
 * error = ""
 * Failed without error (incorrect test results):
 * success = "false"
 * total_tests = tested > passed
 * error = ""
 * Failed with error:
 * success = "false"
 * total_tests > tested > passed
 * error != ""