A Representational State Transfer (REST) Interface follows the principles of being client server, stateless, cacheable and layered (forwardable). The typical set of instructions corresponds to those of HTTP: POST (create), GET (read), PUT (update), DELETE (delete) and the primary mechanism of control is the URL.
The core URL is base_url/package_id where the base_url is the url for the server and interface (e.g. https://wirl.api.sil.org) and the package_id is the id of the package (bundle or resource) of interest.
| GET | Returns the package. No authentication required. |
| PUT | Not used |
| POST | Not used |
| DELETE | Not used |
The server may not necessarily return the package being asked for directly. It may use a redirect to point the calling application to where the package may be found. Thus the REST interface may return the following return codes:
| 200 | OK. The package contents are enclosed with this response. |
| 303 | See other. The body of the response is a URL to GET from to get the resource. |
| 304 (not yet implemented) | Not Modified. The server tracks the time of when resources change and so can help clients with respect to caching and conditional requests. |
| 404 | The package id is wrong or unavailable for this platform. |
| 500 | Internal error for unforeseen problems. |
The following GET request header fields will be supported by the server (not yet implemented):
| If-Modified-Since | Only send the package if it has changed since the given date, else return 304. |
| If-None-Match | Only send the package if its checksum has changed, else return 304. |
| User-Agent | Extract architecture and platform information from the User-Agent string to save requiring such information as parameters within the requested URL (API). This information is fallback information and is overridden if specified in the URL. |
Further parameters in the URL can be used to refine what is received. Parameters consist of key=value pairs separated by &. The parameters are separated from the rest of the URL using ?.
| type | Resource type |
| engine | Software that uses the resource; eg., Keyman, MSKLC, Graphite, Ekaya |
| engineversion | Earliest version of the engine that will handle the resource |
| os | Specifies the operating system the information is for. |
| osversion | Version of the operating system the resource is appropriate for |
| version | Used to request a particular version of a resource, rather than the latest |
| xparam | A type-specific extra parameter that is used to further select what resource is returned (see below) |
| raw | This parameter changes how information is returned. The default is 0 and returns the package. A value of 1 asks the server to return a CSV list of all the information it holds on the packageId requested. |
| test | If non-zero returns empty content. Used for testing that the server would produce something of interest if so requested. |
For an engine, the version is the earliest version that will handle the resource.
| keyman | 6 | Keyman 6. All keyboards are forwardly compatible |
| keyman | 7 | Keyman 7. All keyboards are forwardly compatible |
| keyman | 8 | Keyman 8. All keyboards are forwardly compatible |
| teckit | ??? | |
| graphite | 1.3.5 | E.g., Awami needs collision fixing |
| hunspell | ||
| lo-spell | 4.1 | |
| mozilla-spell | 4.1 |
We list here all the different architectures that can take an osversion parameter and what the values mean. Notice that a resource appropriate for a given osversion may or may not be appropriate for a later osversion. An os value of win* here includes all the different windows os values: win64, win32.
| win* | 5 | Windows XP |
| win* | 6 | Windows Vista |
| win* | 7 | Windows 7 |
| win* | 8 | Windows 8 |
| linux | ||
| ubuntu |
For each class/kind of a resource we list the possible resource types that are available and what they return. In addition, architecture types are listed. The default type is listed first.
A font resource references a single font. A different resource id is used for different subfamilies: bold, italic, etc.
| type | arch | returns |
| ttf (default) | all | .ttf |
| woff | all | .woff |
| woff2 | all | .woff2 |
| exe | all | .exe installer |
It is not likely, but theoretically possible, to have an .exe that installs a single font.
A font collection resource references a set of related fonts, such as a family of regular/bold/italic/bold-italic fonts.
| type | arch | datatype | returns |
| zipttf (default) | all | fontcollection | .zip of .ttf files |
| zipwoff | all | fontcollection | .zip of .woff files |
| exe | win | fontcollection | .exe installer |
Font and Font Collection resources may have an extra parameter which selects a particular area subset. If no specified subset is available, the complete font is returned.
| xparam | meaning |
| Afr | subset for Africa |
| Viet | subset for Vietnamese |
| etc. |
For a single layout there are often many different resources available. The datatype returned is "keyboard".
| type | os | returns | notes |
| source | all | .kmn | works for KMFL as well |
| kmp | all | .kmp | good to pass engineversion of Keyman the .kmx is against |
| kmx | all | .kmx | |
| source | Windows | .klc | |
| mskbd | Windows, win32 | .dll | pass osversion if possible |
| mskbd | Windows, win32 | .dll | pass osversion if possible |
| ldmlkb (default) | all | .xml | |
| mackbd | all | .keylayout | returns source xml for Mac keyboard layouts |
A spell checker is a word list using the Hunspell .dic format. There may or may not be an associated .aff file. A simple word list as a .txt file is also permitted.
| type | engine | returns | datatype |
| hunspell | hunspell | .zip | spell-check |
| wordlist | .txt | spell-check |
If both files exist, the WIRL URL field may indicate a directory that includes both of the files. WIRL will return a ZIP file including the two files.
Currently the only such URLS that are supported for creating a ZIP are for materials in GitHub; e.g., https://github.com//silnrsi/wsresources/tree/master/resources/x/xyz/*.*.