API Reference
From Open Siddur Project Development Wiki
This is a reference for the API that will be in versions 0.4.5 and above. The code currently resides in the xmlapi branch on git. It is not intended to be comprehensive. Instead, it is intended to provide examples for how to do common tasks.
Important note about HTTP methods: Because of a bug/feature in eXist, the API can't use HTTP PUT or HTTP DELETE directly. Instead, when an API call says PUT or DELETE, you MUST use HTTP POST and provide an additional HTTP header:
X-HTTP-Method-Override: [real method]
Most APIs will return HTML service discovery information if called with HTTP GET with the Accept header is "application/xhtml+html"
Most APIs will run their test suites and report results if called with HTTP GET and query parameter ?_test=1 (or ?_test=[test path]). APIs that support testing will indicate it in one or more html:link elements in the html:head section of their service discovery calls.
Contents |
Authentication
Two forms of authentication are allowed:
- Session-based authentication: use the login and logout APIs, pass the session cookie with each transaction
- HTTP Basic authentication: pass the standard HTTP Basic headers with each transaction, no login/logout required
Many APIs require authentication, but the authentication information is not shown in the examples.
Data format
Many of the APIs support more than one data format. Common data formats by MIME type are:
- text/plain
- Plain UTF-8 encoded text with no markup
- application/xhtml+xml, text/html
- XHTML. HTTP GET in HTML mode usually returns the service discovery page.
- application/xml
- XML data, which may or may not be TEI.
- application/tei+xml
- TEI fragments or a complete TEI document.
- application/x-www-form-urlencoded
- URL-encoded key-value pairs, as commonly sent by HTML forms.
To specify that data should be received in a given format, put the MIME type in the Accept header of the HTTP GET request. If the API can't send data in the specified format, it will return HTTP status code 406.
To specify that data is being sent in a given format, put the MIME type in the Content-type header of the HTTP POST request.
The default format is usually application/xhtml+xml
The service discovery mode (usually obtained through HTTP GET in XHTML format) will tell you what data formats are supported by its subordinate APIs.
HTTP return codes
The API uses consistent HTTP status codes to indicate success or failure.
Success codes
- 200 OK
- the transaction completed successfully and there is data returned
- 201 Created
- the transaction completed successfully and created a new object. The Location header may contain the object's URI.
- 202 Accepted
- the transaction completed successfully, but the action will be performed in the background
- 204 No content
- the transaction completed successfully, but there is nothing to return
Failure codes
- 400 Bad request
- Something is wrong with the data that was sent. Usually accompanied by an error message.
- 401 Authorization required
- The requested transaction requires log in, but you are not logged in
- 403 Forbidden
- The requested transaction requires log in with specific credentials, but you don't have them
- 404 Not found
- The API cannot be found or the requested document is inaccessible to you
- 406 Unacceptable
- The Accept header requests a specific return content type, but the API can't serve it
- 500 Internal error
- Something went wrong in the server. Usually indicates a bug, bad hardware, low memory, or the like.
Data model
The data model of an Open Siddur document consists of the following main sections:
- Text repository
- stores short segments of text as tei:seg elements, referencable by @xml:id. The repository is an unordered list.
- Selection
- An ordered list of tei:ptr elements, referencable by @xml:id that point into the document's text repository or to concurrent hierarchies in other documents.
- Views
- Each view imposes one type of hierarchical order on the elements of the selection. It consists of hierarchically ordered elements (examples: tei:p, tei:s, tei:div, tei:ab, tei:lg, tei:l) that, at the lowest level, contain pointers (tei:ptr elements) that point into the selection.
- Concurrent hierarchies
- A selection and a set of views comprises one set of concurrent hierarchies.
User management
Create a new user
> PUT /code/api/user/[username] > Accept: */* > Content-Type: application/x-www-form-urlencoded > password=[password] < HTTP/1.1 201 Created < Set-Cookie: JSESSIONID=[Login session ID];Path=/
Determine if a user exists
> GET /code/api/user/[existing user] > < HTTP/1.1 200 OK
> GET /code/api/user/[nonexisting user] > < HTTP/1.1 404 Not Found
Log in
> PUT /code/api/user/login/[username] > Content-Type: application/x-www-form-urlencoded > password=[password] < HTTP/1.1 204 No Content
Once logged in, a session cookie keeps track of the logged in user. You must transmit the session cookie along with all future requests. Login sessions expire after 20 minutes of inactivity.
Log out
> POST /code/api/user/logout < HTTP/1.1 204 No Content
Change a password
> PUT /code/api/user/[username] > Content-Type: application/x-www-form-urlencoded > password=[new password] < HTTP/1.1 204 No content
Get profile properties
Supported profile properties are name, email, and orgname (affiliation to an organization).
> GET /code/api/user/testuser/name > Accept: application/xml < HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> <tei:name xmlns:tei="http://www.tei-c.org/ns/1.0"> <tei:forename>Test</tei:forename> <tei:surname>User</tei:surname> </tei:name>
Set profile properties
> PUT /code/api/user/[username]/name > Content-Type: application/x-www-form-urlencoded > name=Test User < HTTP/1.1 204 No Content
Data API
Create a new document
New documents can be created two ways:
- Post a main title (as below). The new document will contain a blank JLPTEI template.
- Post an entire valid JLPTEI document
The API-accessible location of the document will be returned in the Location header.
> POST /code/api/data/original > Content-Type: application/xml <?xml version="1.0"?> <tei:title type="main" xmlns:tei="http://www.tei-c.org/ns/1.0">My New Document</tei:title> < HTTP/1.1 201 Created < Location: /code/api/data/original/My%20New%20Document_1
Remove a document
> DELETE /code/api/data/original/Document < HTTP/1.1 204 No Content
Note: If you try to remove a document that other documents to which other documents make reference, you will get an HTTP 400 error. The object will be a list of all documents where the references are.
> DELETE /code/api/data/original/Psalms001
< HTTP/1.1 400 Bad Request
< Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<error>
<path>/code/api/data/original/Psalms001</path>
<message>You cannot delete a document that other documents reference. The other documents are listed.</message>
<object>
<reference>/code/api/data/notes/wlc</reference>
<reference>/code/api/data/original/Psalms</reference>
</object>
</error>Search API
- Search-capable API calls all use the same parameter set.
- Search capability can be found by calling the service discovery API and checking for an html:link to the search description.
- The search API will never return results from inaccessible documents.
Common parameters
A basic search involves calling an API with the query parameter
?q=query
Additional parameters are:
- start=n
- Start the list from result n (an integer)
- max-results=n
- Return no more than n results per page
- owner=user
- List only results that are in documents owned by user
- group=group
- List only results that are in documents owned by group
