-
Notifications
You must be signed in to change notification settings - Fork 19
api
Yi Xing edited this page Feb 14, 2024
·
5 revisions
For an up-to-date API reference, please read the code (/server/app/api
) directly. There's comment and I think it's clear enough, hopefully…
- Almost all APIs accept and return JSON data.
- Languages are represented with ISO 639-1 (two-letter) codes.
- group: A group has a name and a set of languages.
- grouping: Groupings define the many-to-many relationship between groups and dictionaries.
- word: The headword verbatim, as it appears in the dictionary.
- key:
- Denotes the word normalised (stripped of diacritics and punctuation and converted to lowercase).
- Denotes the search term, matches key rather than word.
- source: A directory containing the dictionaries to be used. Subdirectories are recursively searched.
- Endpoint:
/api/suggestions/<group_name>/<key>
- Method: GET
- Parameters:
-
group_name
: The name of the group to search in. -
key
: The key to search for. -
timestamp
(optional): The timestamp of the request, in milliseconds since the epoch.
-
- Returns: An object, with:
- If
timestamp
is set:-
suggestions
: an array of suggestions, -
timestamp
: the request timestamp sent back as is.
-
- Otherwise:
-
suggestions
: an array of suggestions, -
timestamp
: the timestamp of the request received by the server, in seconds since the epoch.
-
- If
- Description: Matching order:
- The key itself if it is a word of any language in the group, inflected or not. (e.g., in Portuguese, avo -> [avo, avó, avô], otima -> ótima)
- Words beginning with the key (
key%
). - Words containing the key (
%key%
), if both-sides expansion is enabled. - Spelling suggestions, when the three previous steps yield no results.
- Endpoint:
/api/query/<group_name>/<key>
- Method: GET
- Parameters:
-
group_name
: The name of the group to search in. -
key
: The key to search for. -
dicts
(bool, optional): Include dictionaries in which the key is found in the response (default is False).
-
- Returns:
- If
dicts
is False: HTML content. - If
dicts
is True: An object with the fields:-
articles
: HTML content. -
dictionaries
: An array of names of the dictionaries in which the key is found.
-
- If
- Description: Query a dictionary group for a specific key and retrieve matching articles.
- Endpoint:
/api/lookup/<dictionary_name>/<key>
- Method: GET
- Parameters:
-
dictionary_name
: The name of the dictionary to search in. -
key
: The key to search for.
-
- Returns: HTML content.
- Description: Query a single dictionary for a specific key and retrieve matching articles. Now only used for internal cross references.
- Please call validator methods before calling the ones in this section.
-
dictionary_name
is used internally to identify the dictionary, whiledictionary_display_name
is used for display purposes and can be modified by the user.
- Endpoint:
/api/management/formats
- Method: GET
- Returns: An array of supported formats.
- Description: Get the list of supported formats.
- Endpoint:
/api/management/dictionaries
- Method: GET
- Returns: An array of objects, with the fields:
dictionary_display_name
dictionary_name
dictionary_format
dictionary_filename
- Description: Get the list of dictionaries.
- Method: POST
- Parameters: Request body is an object with the fields:
dictionary_display_name
dictionary_name
dictionary_format
dictionary_filename
group_name
- Returns: An object with two fields:
-
dictionaries
: the list of dictionaries -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Add a dictionary.
- Method: DELETE
- Parameters: Request body is an object with only one field
name
(the name of the dictionary to delete). - Returns: An object with two fields:
-
dictionaries
: the list of dictionaries -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Delete a dictionary by name.
- Method: PUT
- Parameters: Request body is an array of dictionaries, with all four fields:
dictionary_display_name
dictionary_name
dictionary_format
dictionary_filename
- Returns: The list of dictionaries, reordered.
- Description: Reorder two dictionaries; raises an exception if more than two dictionaries are reordered.
- Endpoint:
/api/management/dictionary_name
- Method: PUT
- Parameters: Request body is an object with two fields:
-
name
: the name of the dictionary -
display
: new display name
-
- Returns:
{'success': True}
- Description: Change the display name of a dictionary.
- Endpoint:
/api/management/sources
- Method: GET
- Returns: An array of strings.
- Description: Get the list of sources.
- Method: POST
- Parameters: Request body is an object with the field
source
. - Returns: The list of sources.
- Description: Add a source.
- Method: DELETE
- Parameters: Request body is an object with the field
source
. - Returns: THe list of sources.
- Description: Delete a source.
- Endpoint:
/api/management/scan
- Method: GET
- Returns: An object with two fields:
-
dictionaries
: the list of dictionaries -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Rescan all sources and update the list of dictionaries together with groupings.
- Endpoint:
/api/management/groups
- Method: GET
- Returns: An array of objects with the fields:
-
name
: the name of the group -
lang
: the set of languages of the group
-
- Description: Get the list of groups.
- Method: POST
- Parameters: Request body is an object with two fields:
-
name
: the name of the new group -
lang
: the set of languages of the group
-
- Returns: An object with two fields:
-
groups
: the list of groups -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Add a group.
- Method: DELETE
- Parameters: Request body is an object with the field
name
. - Returns: An object with two fields:
-
groups
: the list of groups -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Remove a group
- Method: PUT
- Parameters: Request body is a list of groups with both fields.
- Returns: The list of groups, reordered.
- Description: Reorder two groups; raises an exception if more than two groups are reordered.
- Endpoint:
/api/management/group_lang
- Method: PUT
- Parameters: Request body is an object with two fields:
-
name
: the name of the group -
lang
: the new languages of the group
-
- Returns: The list of groups.
- Description: Change the languages of a group.
- Endpoint:
/api/management/group_name
- Method: PUT
- Parameters: Request body is an object with two fields:
-
old
: the group's existing name -
new
: new name to be assigned to the group
-
- Returns: An object with two fields:
-
groups
: the list of groups -
groupings
: a mapping of group names to sets of dictionaries
-
- Description: Change the name of a group.
- Endpoint:
/api/management/dictionary_groupings
- Method: GET
- Returns: A mapping of group names to sets of dictionaries.
- Description: Get the relationship between dictionaries and groups.
- Method: POST
- Parameters: Request body is an object with two fields:
-
group_name
: the name of the group -
dictionary_name
: the name of the dictionary
-
- Returns: A mapping of group names to sets of dictionaries.
- Description: Add a dictionary to a group.
- Method: DELETE
- Parameters: Request body is an object with two fields:
-
group_name
: the name of the group -
dictionary_name
: the name of the dictionary
-
- Returns: A mapping of group names to sets of dictionaries.
- Description: Remove a dictionary from a group.
- Endpoint:
/api/management/history
- Method: GET
- Returns: A list of strings.
- Description: Get the lookup history.
- Method: GET
- Returns: An empty list.
- Description: Clear lookup history.
- Endpoint:
/api/management/history_size
- Method: GET
- Returns: An object with the field
size
. - Description: Get the lookup history size.
- Method: PUT
- Parameters: Request body is an object with the field
size
. - Returns: A list of strings (the lookup history).
- Description: Change the lookup history size.
- Endpoint:
/api/management/num_suggestions
- Method: GET
- Returns: An object with the field
size
. - Description: Get the suggestion size.
- Method: PUT
- Parameters: Request body is an object with the field
size
. - Returns: An object with the field
size
. - Description: Change the suggestion size, which, if smaller than 1, will be set to 1 and returned.
- Endpoint:
/api/validator/dictionary_info
- Method: POST
- Parameters: Request body is an object with four fields:
dictionary_display_name
dictionary_name
dictionary_format
dictionary_filename
- Returns: An object with the field
valid
(bool). - Description: Validate dictionary information.
- Endpoint:
/api/validator/source
- Method: POST
- Parameters: Request body is an object with the field
source
. - Returns: An object with the field
valid
(bool). - Description: Validate the new source directory.
- Endpoint:
/api/validator/test_connection
- Method: GET
- Returns:
{'success': True}
- Description: Test the connection to the server.