.. _api:

===============
API Description
===============

Abstract
========

This is a description of the **query service**.

Purpose
=======

The purpose of the *query service* is to provide programmers a high-level
api to Windchill content items of Windchill business objects.

URLs
====

The API may be accessed by using **HTTP Requests** to the following URLs.

Base URL
--------
:BASE URL: `<<windchill host>>:<<port>>/<<web service>>/servlet/nexiles/tools/services/query`

The URLs below need the **base url** prefixed -- e.g. to fetch the version
one would use a URL like::

    http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/version


API URLs
--------

The following URLs define the API to the query service:

+------------------------------+-----------+-------------------------------------------------------+
| URL                          | Method    | Purpose                                               |
+==============================+===========+=======================================================+
| query/version                | GET       | plug-in version                                       |
+------------------------------+-----------+-------------------------------------------------------+
| query/1.0/api.json           | GET       | JSON api description                                  |
+------------------------------+-----------+-------------------------------------------------------+
| query/1.0/query              | POST, GET | paged query open :ref:`query_open`                    |
+------------------------------+-----------+-------------------------------------------------------+
| query/1.0/query/<session_id> | GET       | paged query fetch pages :ref:`query_get_page`         |
+------------------------------+-----------+-------------------------------------------------------+
| query/1.0/query/<session_id> | DELETE    | close paged quuery session :ref:`query_session_close` |
+------------------------------+-----------+-------------------------------------------------------+


API: Version
============

:URL: `query/version`
:method: `GET`

This fetches the *version* of the **query service** plug-in.

Data Format
-----------

The result of the **HTTP GET** is a JSON document, which has the following
structure::

    {
        version: "0.1dev",
        build: 4,
        date: "2013-04-15"
    }

Example
-------

Getting the plug-in version using CURL::

    $ curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/version
    {
      "version": "0.1dev",
      "build": 0,
      "date": "2013-04-04"
    }

Using jQuery::

    $.ajax({
        url: "/Windchill/servlet/nexiles/tools/services/query/version",
        context: document.body,
        success: function(data) {
            console.log("plug-in version" + data.version);
        }
    });


.. _query_open::

API: open paged query session
=============================

:URL: `query/1.0/query`
:method: `GET` or `POST`

Open a **new** paged query session.  The response will contain the
**session ID** to be used in the :ref:`query_get_page` and
:ref:`query_session_close` API calls.

.. note:: If the query results "fit" into one reply, then a `session_id` of
    `0` (zero) is returned.  The :ref:`query_get_page` API MUST NOT be
    called (there's no more pages).

URL Parameters
--------------

**q**
    :type: JSON
    :default: none
    :required: **yes**

    This URL parameter is used to specify the query to be performed.  It
    can be specified multiple times -- in this case a logical **OR** is
    performed.

    See also :ref:`queries`

**page**
    :type: **integer**
    :default: `0`
    :required: **no**

    The *page number* to fetch.  Page counting is zero-based.

**start**
    :type: **integer**
    :default: `0`
    :required: **no**

    The start offset for the initial (first) request.

**limit**
    :type: **integer**
    :default: `25`
    :required: **no**

    The *page size*, i.e. the maximum number of results to return per
    request.

Query Format
------------

See :ref:`queries` for the query format used.

.. note:: The result will contain also the query used.


Result Data Format
------------------

See :ref:`response-format`

.. _query_get_page::

API: open paged query session
=============================

:URL: `query/1.0/query/<session_id>`
:method: `GET`

Get a page from an open session.  The `session_id` is the ID returned by
the :ref:`query_open` API call.

.. note:: A `session_id` of `0` is invalid for this call - see
    :ref:`query_open`

**page**
    :type: **integer**
    :default: `0`
    :required: **no**

    The *page number* to fetch.  Page counting is zero-based.

**start**
    :type: **integer**
    :default: `0`
    :required: **no**

    The start offset for the initial (first) request.

**limit**
    :type: **integer**
    :default: `25`
    :required: **no**

    The *page size*, i.e. the maximum number of results to return per
    request.

**close**
    :type: **integer**
    :default: `0`
    :required: **no**

    Optionally specify this to be `1` on the **last request** to close the
    session.  For a more explicit way see :ref:`query_session_close`

Result Data Format
------------------

See :ref:`response-format`

.. _query_session_close::

API: close session
==================

:URL: `query/1.0/query/<session_id>`
:method: `DELETE`

Close a session.

**session_id**
    :type: **integer**
    :default: N/A
    :required: **yes**

    The session ID of the session to close.


Result Data Format
------------------

The response is::

    {
        "success": true,
        "session_id": <<the session id passed>>
    }

.. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: