api

SilverDict API Documentation

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…

General notes

• Almost all APIs accept and return JSON data.
• Languages are represented with ISO 639-1 (two-letter) codes.

Terminology

• 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.

Lookup

Suggestions

• 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.
• Description: Matching order:
  1. 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)
  2. Words beginning with the key (key%).
  3. Words containing the key (%key%), if both-sides expansion is enabled.
  4. Spelling suggestions, when the three previous steps yield no results.

Lookup

• 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.
• Description: Query a dictionary group for a specific key and retrieve matching articles.

Lookup (legacy)

• 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.

Management

General notes

• Please call validator methods before calling the ones in this section.
• dictionary_name is used internally to identify the dictionary, while dictionary_display_name is used for display purposes and can be modified by the user.

Supported formats

• Endpoint: /api/management/formats
• Method: GET
• Returns: An array of supported formats.
• Description: Get the list of supported formats.

Dictionaries

• Endpoint: /api/management/dictionaries

Get 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.

Add a dictionary

• 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.

Delete 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.

Reorder dictionaries

• 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.

Dictionary display name

• 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.

Sources

• Endpoint: /api/management/sources

Get sources

• Method: GET
• Returns: An array of strings.
• Description: Get the list of sources.

Add a source

• Method: POST
• Parameters: Request body is an object with the field source.
• Returns: The list of sources.
• Description: Add a source.

Delete a source

• Method: DELETE
• Parameters: Request body is an object with the field source.
• Returns: THe list of sources.
• Description: Delete a source.

Rescan sources

• 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.

Groups

• Endpoint: /api/management/groups

Get 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.

Add a group

• 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.

Delete 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

Reorder groups

• 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.

Change group languages

• 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.

Change group name

• 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.

Dictionary groupings

• Endpoint: /api/management/dictionary_groupings

Get groupings

• Method: GET
• Returns: A mapping of group names to sets of dictionaries.
• Description: Get the relationship between dictionaries and groups.

Add a dictionary to a group

• 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.

Remove a dictionary from 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.

Lookup history

• Endpoint: /api/management/history

Get history

• Method: GET
• Returns: A list of strings.
• Description: Get the lookup history.

Clear history

• Method: GET
• Returns: An empty list.
• Description: Clear lookup history.

History size

• Endpoint: /api/management/history_size

Get history size

• Method: GET
• Returns: An object with the field size.
• Description: Get the lookup history size.

Change 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.

Suggestion size

• Endpoint: /api/management/num_suggestions

Get suggestion size

• Method: GET
• Returns: An object with the field size.
• Description: Get the suggestion size.

Change 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.

Validators

Dictionary information

• 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.

Source

• 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.

Test connection

• Endpoint: /api/validator/test_connection
• Method: GET
• Returns: {'success': True}
• Description: Test the connection to the server.