As work-in-progress in the Fuseki UI, here is some rough content for
documentation to give an idea of the general direction.
The code does not yet match the documentation - it's quite close but
writing the documentation showed ways in which the coded implementation
was plain odd.
Summary:
{name} is the dataset URL component e.g. /ds has name "ds"
| Method | URL pattern | Description
|-----------|------------------------|----------------------------|
| GET | /$/server | Server details
| GET | /$/ping | Server liveness ping
| POST | /$/ping | Server liveness ping
| POST | /$/server/shutdown | Shutdown (graceful)
|
| POST | /$/datasets/ | Add new dataset (assembler)
| GET | /$/datasets/ | List datasets
| DELETE | /$/datasets/{name} | Delete dataset
| GET | /$/datasets/{name} | Get dataset (assembler)
| POST | /$/datasets/{name}?state=dormant
| POST | /$/datasets/{name}?state=active
| POST | /$/backup/{name} |
|
| GET | /$/stats/ | Statistics
| GET | /$/stats/{name} | Statistics for a dataset
Andy
---------------------------------------------
# Fuseki Administration
> _ These functions are available in version 1.0.1 and later._
> _ Three pages: this one, HTTP protocol, stats details
> _@@ Check links when sections stable_
* [Overview](#overview)
* [Fuseki administration UI](#Fuseki)
* [Enabling Administration Functions](#enabling-administration-functions)
* [Security](#security)
* [Naming of Datasets](naming-of-datasets)
Control of the server is via [an HTTP interface](admin-http.html).
# Overview
A Fuseki server can be controlled through an administration API.
The API is based on HTTP operations so administration tasks can be scripted
or invoked by a JavaScript web application.
The state of a server is recorded in a persistent database. If a server
is stopped
and restarted, the stet of the server, in terms of datasets services
and configuration, is as it was at the point of stopping.
The administration operations available cover:
* Reporting the datasets available on the server, and their configuration
* Adding and removing datasets to a running server
* Being about to take a dataset temporarily offline
* Backup
* Report statistics of server and service usage
## Fuseki administration UI
The server can be controlled by a web front end. This is accessed via
the URL
for the server when the administration functions are running. This may be a
different port to the SPARQL services.
## Enabling administration functions
Adding `--mgt` to the start up arguments, enables the administrative
functions
on the same port as the main publishing operations. A different port can
be used
with `--mgtPort=3131`.
## Security
These functions all use URLs with a defined pattern (they start with "`/$`")
which is reserved for administration operations. Common web application
container security can be used to restrict access. A Fuseki publishing
server
can be run without any administration functions.
## Naming of Datasets
In administration operations, the dataset name is appended to the
operation. For
example, `http://host:port/$/datasets/ds` accesses the assembler description
of the dataset.
There is also an internal name, generated by the server which is a UUID.
This UUID is never reused even if the dataset name is reused after the
first use is deleted.
## Status
> Work-in-progress (December 2013)
> _@@Currently_ <br />
> No `--mgt`<br />
> Use `--mgtPort=3131`, or `--mgtPort=0` for "same port"
## To do
Server config file as an alternative to the command line.
Not implemented yet: `/$/server/shutdown`
* * *
# Other material
## Naming of datasets (overview)
> _@@ This needs to go somewhere else_
Each dataset has a unique name (written `*{name}*` below). This name is
used to generate the URL its services are accessed by and also to
identify it in administration operations.
The `*{name}*` must not start with a `/` and must be a valid URL component.
The dataset services can accessed at `http://host:port/*{name}*/*{service}*`
`http://host:port/ds/sparql`
_@@ relatively untested - dataset names with `/` in them_
* * *
> **admin-http.html**
# HTTP Administration Functions
* [Details of operations](#operations)
* [Server Information](#server-information)
* [Datasets and Services](#datasets-and-services)
* Adding a Dataset and its Services
* Removing a Dataset
* Dormant and Active
* [Removing a dataset](#remove-dataset)
* [Statistics](#statistics)
These are enabled by starting the server with argument `--mgt`
## Operations
| Method | URL pattern | Description |
|-----------------|------------------------|---------------|
| <tt>GET</tt> | `/$/server` | |
| <tt>GET</tt> | `/$/ping` | |
| <tt>POST</tt> | `/$/ping` | |
| <tt>POST</tt> | `/$/server/shutdown` | |
||
| <tt>POST</tt> | `/$/datasets/` | |
| <tt>GET</tt> | `/$/datasets/` | List details |
| <tt>DELETE</tt> | `/$/datasets/*{name}*` | |
| <tt>GET</tt> | `/$/datasets/*{name}*` | |
| <tt>POST</tt> | `/$/datasets/*{name}*?state=dormant` | |
| <tt>POST</tt> | `/$/datasets/*{name}*?state=active` | |
| <tt>POST</tt> | `/$/backup/*{name}*` | |
||
| <tt>GET</tt> | `/$/stats/` | |
| <tt>GET</tt> | `/$/stats/*{name}*` | |
## Server Information
> **`/$/server/`**
The URL `/$/server` returns details about the server and it's current
status in JSON.
### Backup
> **`/$/backup/*{name}*`**
## Ping
The URL `/$/ping` is a guaranteed low cost point to test whether a server
is running or not. It returns no other information other than to
respond to the
request over `GET` or `POST` (to avoid any HTTP caching) with a 200
response.
## Datasets and Services
> **`/$/datasets/`**
`/$/datasets/` is a container representing all datasets present in the
server.
`/$/datasets/*{name}*` names a specific dataset.
### Adding a Dataset and its Services.
A dataset set is added to a running server by `POST`ing the assembler
description to the datasets container URL `/$/datasets`. The dataset
name is taken from the assembler description.
The assembler description contains data and service.
### Removing a Dataset
Note: `DELETE` means "gone for ever". The dataset and the details of its
configuration are completely deleted and can not be recovered.
> _@@ We could keep everything around as the graph are named by UUID_
### Dormant and Active
A dataset can be made "dormant" - not accepting operations.
Transition to "dormant" is graceful - outstanding requests are completed.
## Statistics
> **`/$/stats/*{name}*`**
Statistics can be obtained for each dataset or all datasets in a single
response.
`/$/stats/` is treated as a container for this information.
See [Fuseki Statistics](fuseki-stats.html) for details.
* * *
> _@@ Separate page
Each dataset and each service of a dataset keeps counters as to the number
of incoming requests, number of successful requests, number of bad requests
(i.e client errors), and number of failing requests (i.e. server errors).
Statistics are returned as JSON. They are also available via JMX.
{ "datasets" : {
"/ds" :
{ "Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"services" : {
"query" :
{"QueryExecErrors" : 0 ,
"QueryTimeouts" : 0 ,
"Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"endpoints" : [
"query" ,
"sparql"
]
} ,
"update" :
{"Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"UpdateExecErrors" : 0 ,
"endpoints" : [ ]
} ,
"upload" :
{"Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"endpoints" : [ ]
} ,
"gspRead" :
{"GSPdelete" : 0 ,
"GSPdeleteBad" : 0 ,
"GSPdeleteGood" : 0 ,
"GSPget" : 0 ,
"GSPgetBad" : 0 ,
"GSPgetGood" : 0 ,
"GSPhead" : 0 ,
"GSPheadBad" : 0 ,
"GSPheadGood" : 0 ,
"GSPoptions" : 0 ,
"GSPoptionsBad" : 0 ,
"GSPoptionsGood" : 0 ,
"GSPpatch" : 0 ,
"GSPpatchBad" : 0 ,
"GSPpatchGood" : 0 ,
"GSPpost" : 0 ,
"GSPpostBad" : 0 ,
"GSPpostGood" : 0 ,
"GSPput" : 0 ,
"GSPputBad" : 0 ,
"GSPputGood" : 0 ,
"Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"endpoints" : [ "data" ]
} ,
"gspReadWrite" :
{"GSPdelete" : 0 ,
"GSPdeleteBad" : 0 ,
"GSPdeleteGood" : 0 ,
"GSPget" : 0 ,
"GSPgetBad" : 0 ,
"GSPgetGood" : 0 ,
"GSPhead" : 0 ,
"GSPheadBad" : 0 ,
"GSPheadGood" : 0 ,
"GSPoptions" : 0 ,
"GSPoptionsBad" : 0 ,
"GSPoptionsGood" : 0 ,
"GSPpatch" : 0 ,
"GSPpatchBad" : 0 ,
"GSPpatchGood" : 0 ,
"GSPpost" : 0 ,
"GSPpostBad" : 0 ,
"GSPpostGood" : 0 ,
"GSPput" : 0 ,
"GSPputBad" : 0 ,
"GSPputGood" : 0 ,
"Requests" : 0 ,
"RequestsBad" : 0 ,
"RequestsGood" : 0 ,
"endpoints" : [ ]
}
}
}
}
}
