Extension:WikiLambda/API

From mediawiki.org
Jump to navigation Jump to search

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.


action=wikilambda_fetch[edit]

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 #list=wikilambdaload_zobjects

Documentation[edit]

Method: GET

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

Response:

{
  "Z111": {
    "wikilambda_fetch": "{\n    \"Z1K1\": \"Z2\",\n    \"Z2K1\": \"Z111\"\n}"
  },
  "Z112": {
    "wikilambda_fetch": "{\n    \"Z1K1\": \"Z2\",\n    \"Z2K1\": \"Z112\"\n}"
  }
}


Parameters[edit]

zids

required | string

List of ZObject Identifiers (ZIDs) to fetch, separated by pipes.

E.g. zids=Z1|Z2|Z3

language

optional | string

String code for the language in which to return the results. Must be an accepted MediaWiki language code. If not present, the API will return the root label in all available languages.

E.g. language=es


Possible Errors[edit]

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.


#TODO

Invalid ZID

#TODO

Error ZID (Z50 type)

The given ZID is an invalid ZObject ID. This means that it does not follow the expected format of ID starting with the capital letter Z and followed by a natural number.
ZID not found #TODO

Error ZID (Z50 type)

The given ZID does not exist in this wiki.


Examples[edit]

api.php?action=wikilambda_fetch&format=json&zids=Z1
Returns the canonical representation of the ZObject with ZID Z1 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 Z1, Z2 and Z3 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 Z4 and Z6 with its root-level label in Spanish or available fallback languages.


list=wikilambdaload_zobjects[edit]

Similarly to the wikilambda_fetch 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[edit]

Method: GET

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

Response:

{
    "batchcomplete": "",
    "query": {
        "wikilambdaload_zobjects": {
            "Z111": {
                "success": "",
                "data": {
                    "Z1K1": "Z2",
                    "Z2K1": "Z111"
                }
            },
            "Z112": {
                "success": "",
                "data": {
                    "Z1K1": "Z2",
                    "Z2K1": "Z112"
                }
            }
        }
    }
}


Parameters[edit]

wikilambdaload_zids

required | string

List of ZObject Identifiers (ZIDs) to fetch, separated by pipes.

E.g. wikilambdaload_zids=Z1|Z2|Z3

wikilambdaload_language

optional | string

String code for the language in which to return the results. Must be an accepted MediaWiki language code. If not present, the API will return the root label in all available languages.

E.g. wikilambdaload_language=es

wikilambdaload_canonical

optional | boolean

Whether to return the ZObjects in canonical or in its normalized form. The default value is false. If set to true, all the requested ZObjects will be returned in its canonical form. If not set, the ZObjects will be normalized and returned in their normal form, except for the ZList (Z10), which will be still returned as an array.

E.g. wikilambdaload_canonical=1


Possible Errors[edit]

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.

Invalid ZID #TODO

Error ZID (Z50 type)

The given ZID is an invalid ZObject ID. This means that it does not follow the expected format of ID starting with the capital letter Z and followed by a natural number.
ZID not found #TODO

Error ZID (Z50 type)

The given ZID does not exist in this wiki.


Examples[edit]

api.php?action=query&format=json&list=wikilambdaload_zobjects&wikilambdaload_zids=Z1|Z2
Returns the normal JSON representation of the ZObjects with ZID Z1 and Z2 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 Z3 and Z4 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 Z6.



list=wikilambdasearch_labels[edit]

This API query list generator lets you search ZObjects for labels in a given language. It principally exists to support the look-ahead search system.

Documentation[edit]

Method: GET

Request: api.php?action=query&format=json&list=wikilambdasearch_labels&wikilambdasearch_search=foo&wikilambdasearch_language=eu

Response:

{
    "batchcomplete": "",
    "query": {
        "wikilambdasearch_labels": [
            {
                "page_namespace": 2468,
                "page_title": "Z111",
                "page_type": "Z111",
                "label": "foo",
                "page_id": 0,
                "page_content_model": "zobject",
                "page_lang": "eu"
            }
        ]
    }
}


Parameters[edit]

wikilambdasearch_search

required | string

The search term to find in all the present labels.

E.g. wikilambdasearch_search=text

wikilambdasearch_language

required | string

String code for the language in which to return the results. Must be an accepted MediaWiki language code. If the labels aren't present for this language, use fallback languages.

E.g. wikilambdasearch_language=eu

wikilambdasearch_nofallback

optional | boolean

Whether to search only in the given language and not its fallback languages. If set to true, it will ignore the fallback languages and only search in the requested language.

E.g. wikilambdasearch_nofallback=1

wikilambdasearch_exact

optional | boolean

Whether to search for exact matches. If disabled, input will be taken as a case-insensitive, Unicode-normalised search with accents on Latin characters ignored.

E.g. wikilambdasearch_exact=1

wikilambdasearch_type

optional | string

Restrict matches to a specific type of ZObject. If present, the search term will only be matched against the labels of ZObjects of the specified type. This is particularly useful for UI components such as the Type selector, which autocompletes a search input with only available ZType (Z4) objects.

E.g. wikilambdasearch_type=Z4

wikilambdasearch_limit

optional | integer

The maximum number of results to return. The value must be between 1 and 5000. Enter max to use the maximum limit.

E.g. wikilambdasearch_limit=10

wikilambdasearch_continue

optional | integer

When more results are available, use this to continue.

E.g. wikilambdasearch_continue=1


Possible Errors[edit]

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

Examples[edit]

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.