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 query_open
query/1.0/query/<session_id> GET paged query fetch pages query_get_page
query/1.0/query/<session_id> DELETE close paged quuery session 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);
    }
});

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 query_get_page and query_session_close API calls.

Note

If the query results “fit” into one reply, then a session_id of 0 (zero) is returned. The 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 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 Queries for the query format used.

Note

The result will contain also the query used.

Result Data Format

See response-format

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 query_open API call.

Note

A session_id of 0 is invalid for this call - see 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 query_session_close

Result Data Format

See response-format

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>>
}