Context Navigation

TNTBase RESTful API

Testing

For testing RESTful API in general it is convenient to use the Firefox RESTful client plugin: https://addons.mozilla.org/en-US/firefox/addon/9780

All examples were tested on the real system.

Specification

Apart from the exact SVN interface, you can utilize the RESTful API of TNTBase. Besides these facilities, there is a web html interface, which shows directory listing, like it is done in SVN Apache interface with the only exception that it shows only XML files which are currently in TNTBase.

Before reading the specification it is worth getting acquaint with XML result sets, XML execution and error codes.

Retrieving names of documents

Method

URL: /names/getDocNames
- Method: GET
- Query parameters:
  - numResuls - max number of results to be returned (default: -1, which means all possible results)
  - startFrom - starting from N-th result (default: 1, start from the first)
- Returns: text/xml
- Description: returns XML documents names in the TNTBase repository.

Example

URL: http://localhost:8080/TNTBase/restful/names/getDocNames?startFrom=3&numResults=5
Method: GET

Result:

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" startFrom="3" numResults="5">
  <tnt:docname>/omstd/omtypes.omdoc</tnt:docname>
  <tnt:docname>/omstd/s_dist1.omdoc</tnt:docname>
  <tnt:docname>/omstd/permgrp.omdoc</tnt:docname>
  <tnt:docname>/omstd/setname2.omdoc</tnt:docname>
  <tnt:docname>/omstd/poly.omdoc</tnt:docname>
</tnt:results>

Method

URL: /names/getDocNames/{path in the repository}
- Method: GET
- Query parameters:
  - numResults: max number of results to be returned
  - numResults: starting from N-th result
  - recursive (true or false): whether we want to go to the child directories of the {path in the repository} (default: false)
- Returns: text/xml
- Description: returns XML documents names in the TNTBase repository. If recursive parameter is set to false, then we can use simple regexp expressions, like *,? or which stands for all child directories. If recursive is set to true

Example

URL: http://localhost:8080/TNTBase/restful/names/getDocNames/*oms*//?numResults=2
Method: GET

Result: Get all documents' names in root folders which have oms in the middle and all their sub-folders. Moreover, return only two results starting from the first

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" startFrom="1" numResults="2">
  <tnt:docname>/omstd/calculus1.omdoc</tnt:docname>
  <tnt:docname>/omstd/limit1.omdoc</tnt:docname>
</tnt:results>

Operating with contents of documents

Method

URL: /content/docs
- Method: GET
- Query parameters:
  - numResults - max number of results to be returned (default: -1)
  - startFrom - starting from N-th result
- Returns: text/xml
- Description: returns all XML documents in the TNTBase repository as an aggregated document wrapped into results tags

Example

URL: http://localhost:8080/TNTBase/restful/content/docs?numResults=1
Method: GET

Result: The wholde document with its header and DTDs. Note that in the result item you can see the name of a document

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" numResults="1">
  <tnt:doc name="/omstd/calculus1.omdoc">
    <omdoc xmlns="http://www.mathweb.org/omdoc" xmlns:dc="http://purl.org/dc/elements/1.1/" xml:id="calculus1-omdoc">

    <metadata>
      <dc:title>The OpenMath Content Dictionary calculus1.ocd  in OMDoc form</dc:title>
      <dc:creator role="ant">The OpenMath Society</dc:creator>
      // ... more content goes here
  </tnt:doc>
</tnt:results>

Method

URL: /content/docs/{path in the repository}
- Method: GET
- Query parameters:
  - numResults - max number of results to be returned (default: -1)
  - startFrom - starting from N-th result (default: 1)
  - recursive (true or false): whether we want to go to the child directories of the {path in the repository} (default: false)
- Returns: text/xml
- Description: returns XML documents in the TNTBase repository as an aggregated document wrapped into results tags. If recursive parameter is set to false, then we can use simple regexp expressions, like *,? or which stands for all child directories. If recursive is set to true

Example

URL: http://localhost:8080/TNTBase/restful/content/docs/omstd/?recursive=yes&numResults=1
Method: GET

Result: Returns documents (actually only one due to the numResults query parameter) from omstd folder and its subfolders recursevely. Can be substituted by regexp like omstd, but will be not so efficient.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" numResults="1">
  <tnt:doc name="/omstd/calculus1.omdoc">
    <omdoc xmlns="http://www.mathweb.org/omdoc" xmlns:dc="http://purl.org/dc/elements/1.1/" xml:id="calculus1-omdoc">

    <metadata>
      <dc:title>The OpenMath Content Dictionary calculus1.ocd  in OMDoc form</dc:title>
      <dc:creator role="ant">The OpenMath Society</dc:creator>
      // ... more content goes here
  </tnt:doc>
</tnt:results>

Method

URL: /content/doc/{{path to file in the repository}}
- Method: GET
- Query parameters:
  - wrap (true or false): whether we want to retrieve a wrapped document or not (default: false)
  - rev - the revision number of document we want to receive. Default is -1 which means the HEAD revision. Note that you can't retrieve HEAD revision of file other than providing -1. There are some reasons behind it (conceptual, but not technical)
- Returns: text/xml
- Description: returns an XML document. If there is no such a document in TNTBase, then XML wrapper with error code will be returned

Example

URL:
Method: GET

Result: returns the concrete document from TNTBase, or XML error if document does not exist.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns">
  <error>
    <code>1</code>
    <message>
      DOCUMENT_NOT_FOUND :: No such document in database :: /lectures/doc_which_not_exists.omdoc
    </message>
  </error>
</tnt:results>

Method

URL: /content/doc/{{path to file in the repository}}
- Method: PUT
- Accepts: application/xml or text/xml
- Returns: text/xml
- Description: Adds or updates an XML document to TNTBase repository and adds svn:mime-type property as text/xml to it. The XML execution result wrapper is returned in case of success, and 403 Forbidden response otherwise

Example

URL: http://localhost:8080/TNTBase/restful/content/doc/examples/induction.omdoc
Method: PUT

Request body:

<omdoc xmlns="http://you/should/know/it/by/heart.org">
  //There comes weird, but cool OMDOC stuff
</omdoc>

Result: Just an XML execution code. Note that you will receive a 403 FORBIDDEN response if document is not well-formed. This method adds svn:mime-type property which equals to "text/xml" that internally says xSVN that the content should go to TNTBase, thus to be a well-formed document. Generally, if you commit a bunch of XML files one of which is not well-formed, then none of files will be commited (which conforms to SVN ideology, and many others). Note that message element also represents a revision at what it was commited.
```
<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns">
  <execution><code>2</code>
    <message>
      DOCUMENT_ADDED :: The document was added :: /examples/induction.omdoc
      Commit info: r35 at Thu Mar 05 00:29:26 CET 2009
    </message>
  </execution>
</tnt:results>
```

Method

URL: /content/doc/{{path to file in the repository}}
- Method: DELETE
- Returns: text/xml
- Description: Deletes an XML document from HEAD revision of TNTBase repository. The execution result wrapper is returned in case of success, and 403 Forbidden response otherwise.

Example

URL: http://localhost:8080/TNTBase/restful/content/doc/examples/induction.omdoc
Method: DELETE

Result: The document is deleted, and as the evidence, the XML execution code is sent.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns">
  <execution>
    <code>1</code>
    <message>
      DOCUMENT_DELETED :: The document was deleted :: /examples/induction.omdoc
      Commit info: r36 at Thu Mar 05 00:37:52 CET 2009
    </message>
  </execution>
</tnt:results>

Querying TNTBase

Method

URL: /query/{query}
- Method: GET
- Query parameters:
  - numResults - max number of results to be returned (default: -1)
  - startFrom - starting from N-th result (default: 1)
  - omdocNs (true or false): whether we want to bind OMDoc namespace to the empty prefix (default: true)
  - ns - a list of namespaces with prefixes that we want to use when querying. The format is the following: prefix:namespace. Note than prefixes can not be repeated
- Returns: text/xml
- Description: returns wrapped XML results after query execution. One can query the whole collection of TNTBase, the particular document in the database (providing doc(doc_path) in front of query) and collection of particular documents (providing collection(path_with_regexp_symbols)). Note that only relatively short queries can be used in this method due to the URL length constraints

Example

URL: http://localhost:8080/TNTBase/restful/query/doc(/omstd/relation1.omdoc)/omdoc/metadata
Method: GET

Result: Root metadata elements in the /omstd/relation1.omdoc document. Again they are presented in the XML result set.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" startFrom="1" numResults="1">
  <tnt:result>
    <metadata xmlns="http://www.mathweb.org/omdoc">
      <dc:title xmlns:dc="http://purl.org/dc/elements/1.1/">The OpenMath Content Dictionary relation1.ocd  in OMDoc form</dc:title>
      <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/" role="trl">Michael Kohlhase</dc:creator>
      <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/" role="ant">The OpenMath Society</dc:creator>
      //more metadate goes here
    </metadata>
  </tnt:result>
</tnt:results>

Method

URL: /query
- Method: POST
- Accepts: the XQuery query in the body
- Query parameters:
  - numResults - max number of results to be returned (default: -1)
  - startFrom - starting from N-th result (default: 1)
  - omdocNs (true or false): whether we want to bind OMDoc namespace to the empty prefix (default: true)
  - ns - a list of namespaces with prefixes that we want to use when querying. The format is the following: prefix:namespace. Note than prefixes can not be repeated
- Returns: text/xml
- Description: the same as the above method, but contains an XQuery expression in the body of a request, but not as a part of url

Example

URL: http://localhost:8080/TNTBase/restful/query?numResults=1&ns=it_should_be_default_for_all_XML_documents:http://www.mathweb.org/omdoc

Request body:

  collection(//om*td/*)/it_should_be_default_for_all_XML_documents:omdoc/it_should_be_default_for_all_XML_documents:theory/it_should_be_default_for_all_XML_documents:symbol

Method: POST

Result: Returns the first symbol in all documents in all folders which have the begging of om and the ending of td. Note that namespaces' declaration are important in some documents. Note that we use the new namespace prefix only for querying.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns" startFrom="1" numResults="1">
  <tnt:result>
    <symbol xmlns="http://www.mathweb.org/omdoc" name="eq" xml:id="eq">
      <metadata>
        <dc:description xmlns:dc="http://purl.org/dc/elements/1.1/">
          This symbol represents the binary equality function.
        </dc:description>
        <dc:subject xmlns:dc="http://purl.org/dc/elements   /1.1/">eq</dc:subject>
      </metadata>
      <type system="sts.omdoc#sts">
        <OMOBJ xmlns="http://www.openmath.org/OpenMath">
          <OMA>
	    <OMS name="mapsto" cd="sts" />
	    <OMS name="Object" cd="sts" />
	    <OMS name="Object" cd="sts" />
	    <OMS cd="setname2" name="Boolean" />
          </OMA>
        </OMOBJ>
      </type>
    </symbol>
  </tnt:result>
</tnt:results>

Update facilities of TNTBase

Method

URL: /update/{xqupdate}
- Method: GET
- Query parameters:
  - omdocNs (true or false): whether we want to bind OMDoc namespace to the empty prefix (default: true)
  - ns - a list of namespaces with prefixes that we want to use when querying. The format is the following: prefix:namespace. Note than prefixes can not be repeated
  - readonly (true or false): If true, just returns the modified document as a response. Otherwise the changes are committed to TNTBase, and thus the new revision of XML document appears.
- Returns: text/xml
- Description: Perform XQUpdate on the particular document in TNTBase, which mentioned in the XQUpdate (like insert nodes <TNT>I will explode</TNT> after doc(lectures/lecture1.omdoc)/omdoc/metadata/dc:author). The modified document can be either be returned to the user or stored as a new revision in TNTBase.

Example

URL: http://localhost:8080/TNTBase/restful/update/insert nodes <external_metadata>Powered by TNTBase</external_metadata> after doc(/omstd/relation1.omdoc)/omdoc/metadata?readonly=true
Method: GET

Result: Only (because of readonly=true parameter) returns the transformed document which inserts the element after omdoc/metadata in the /omstd/relation1.omdoc document.

<tnt:results xmlns:tnt="http://tntbase.mathweb.org/ns">
  <tnt:result modified_doc="/omstd/relation1.omdoc">
    <omdoc xmlns="http://www.mathweb.org/omdoc" xmlns:dc="http://purl.org/dc/elements/1.1/" xml:id="relation1-omdoc">
      <metadata>
        <dc:title>The OpenMath Content Dictionary relation1.ocd  in OMDoc form</dc:title>
        ... here are some metadata
        <dc:description>
          This CD holds the common arithmetic relations. It is intended
            to be `compatible' with the appropriate MathML elements.
        </dc:description>
      </metadata>
      <external_metadata>
        Powered by TNTBase
      <external_metadata>
      <theory xml:id="relation1">
      //clever theory stuff
        </example>
      </theory>
    </omdoc>
  </tnt:result>
</tnt:results>

Method

URL: /update
- Method: POST
- Accepts: XQUpdate to be processed
- Query parameters:
  - omdocNs (true or false): whether we want to bind OMDoc namespace to the empty prefix (default: true)
  - ns - a list of namespaces with prefixes that we want to use when querying. The format is the following: prefix:namespace. Note than prefixes can not be repeated
  - readonly (true or false): If true, just returns the modified document as a response. Otherwise the changes are committed to TNTBase, and thus the new revision of XML document appears.
- Returns: text/xml
- Description: the same as the above method, but contains an XQUpdate expression in the body of a request, but not as a part of url

Example

URL: http://localhost:8080/TNTBase/restful/update?readonly=false
Method: POST

Request body:

  replace node doc(/omstd/error.omdoc)/omdoc/theory with <example>Last for now, but not least</example>

Result: Commits a new version of the modified document (omstd/error.omdoc). It replaces the whole theory element with the element provided in the body of the request

Download in other formats:

Plain Text