Overview
wsidb reads and writes the WSi database over HTTP. Each request names the WSi version to serve it.
Base URL: https://wsidb.wsoptics.de
| Endpoint | Purpose |
|---|---|
|
The supported WSi versions. |
|
One table as JSON. |
|
All tables in WSi’s binary |
|
Write a set of tables. |
GET /v0/versions is open; every other endpoint requires the headers described
under Requests.
Requests
A request body larger than 8 MiB is rejected with 413.
WSi version
The first path segment after /v0/ names the WSi version to serve the request:
/v0/wsi-<major>-<minor>/... /v0/wsi-<major>/...
Omitting the minor version uses the newest one supported for that major version.
wsi4- is accepted in place of wsi-.
License key
Authorization: Bearer <license-key>
The license key is a UUID. A key that is not valid is answered with 401; a
database the key does not reach, or may not write to, with 403.
Database
The database must be linked to the license key, and is named either by its UUID or by its name:
X-Database-Uuid: <database-uuid> X-Database-Name: <database-name>
The UUID is the preferred handle: a request carrying both headers is served by the UUID, and the name is ignored. Selecting by UUID requires WSi 2.3 or newer. A database whose name contains whitespace can be reached only by its UUID.
GET versions
The WSi versions this service supports.
GET /v0/versions
curl 'https://wsidb.wsoptics.de/v0/versions'[
{"major": 1, "minor": 31},
{"major": 2, "minor": 3}
]The versions come in no particular order.
GET table
One table as JSON.
GET /v0/<wsi-version>/table/<table-type>
<table-type> is a value of WSi’s TableType enumeration, matched
case-sensitively. The values, and the columns each table’s rows hold, are
documented under
Table Documentation.
curl -H 'Authorization: Bearer <license-key>' \
-H 'X-Database-Uuid: <database-uuid>' \
'https://wsidb.wsoptics.de/v0/wsi-2/table/sheetMaterial'The response body is an array of rows. Their columns follow the table type;
the example below is sheetMaterial.
[
{
"identifier": "1.0038",
"name": "1.0038",
"description": ""
}
]GET tables (dat)
All tables at once, in WSi’s binary .dat format.
GET /v0/<wsi-version>/tables/dat
curl -H 'Authorization: Bearer <license-key>' \
-H 'X-Database-Uuid: <database-uuid>' \
-o tables.dat \
'https://wsidb.wsoptics.de/v0/wsi-2/tables/dat'The response body is the raw .dat payload, to be handed to WSi as-is rather
than parsed.
PUT tables
Write a set of tables. The update is applied only if the database stays consistent; on any inconsistency the whole update is aborted and the database is left unchanged.
PUT /v0/<wsi-version>/tables
The body is a JSON object holding the tables to write and how they meet what is
already stored. Each table has a type naming a value of the TableType
enumeration and a content holding rows in the shape that type defines, both
documented under
Table Documentation.
type is matched case-sensitively.
importMode selects how the submitted rows meet the stored ones; omitting it
selects update:
update-
Update only existing rows.
upsert-
Update existing rows and add new ones.
replace-
Replace the stored table with the submitted one.
{
"tables": [
{
"type": "sheetMaterial",
"content": [
{
"identifier": "1.0038",
"name": "1.0038",
"description": ""
}
]
}
],
"importMode": "update"
}curl -X PUT \
-H 'Authorization: Bearer <license-key>' \
-H 'X-Database-Uuid: <database-uuid>' \
--data-binary '@payload.json' \
'https://wsidb.wsoptics.de/v0/wsi-2/tables'A successful write is answered with 200 OK and an empty body.
An update the database rejects is answered with the status describing the
rejection and a JSON body. message describes the rejection; details is
present only for rejections that carry one. An error raised before the update
reaches the database — a missing or invalid header, an unsupported WSi version,
an oversized body — answers plain text, and both shapes are sent as
text/plain.
{
"message": "...",
"details": {}
}