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

:Author:    Stefan Eletzhofer
:Date:      |today|
:State:     **production**

Abstract
========

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

Purpose
=======

The purpose of the *file 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/files`

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/files/version


API URLs
--------

The following URLs define the API to the file service:

+----------------------+--------+----------------------+
| URL                  | Method | Purpose              |
+======================+========+======================+
| files/version        | GET    | plug-in version      |
+----------------------+--------+----------------------+
| files/:oid           | GET    | return list of files |
+----------------------+--------+----------------------+
| files/:oid/:filename | GET    | return file content  |
+----------------------+--------+----------------------+
| files/:oid/:filename | POST   | create update a file |
+----------------------+--------+----------------------+
| files/:oid/:filename | DELETE | delete a file        |
+----------------------+--------+----------------------+


To provide a way to create *stable links* to files, we need a alternate way
to refer to business objects.  For this purpose we'll use the `number` of
business objects.

.. note:: When using **numbers**, the file service assumes `WTDocument`
   types.

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

:URL: `files/version`
:method: `GET`

This fetches the *version* of the **file 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/files/version
    {
      "version": "0.1dev",
      "build": 0,
      "date": "2013-04-04"
    }

Using jQuery::

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

API: File Listing
=================

:URL: `files/`
:method: `GET`

The `GET` on for the list of files takes an *optional* `role` parameter,
where role is the content role or `all` for all roles.  The *default* is
`SECONDARY`.

Example

http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=all
http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=SECONDARY
http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=PRIMARY
http://example.com/Windchill/servlet/nexiles/tools/services/files/OR:wt.doc.WTDocument:4711?role=all

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

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

    {
        "count": <<number of files>>,
        "items": [
            {
                "url": <<url to file content>>,
                "role": <<content role>>
                "mimetype": <<the mime type of the file>>,
                "filename": <<the file name>>
                "size": <<the file size in bytes>>
            },
            ...
        ]
    }

Examples
--------

Using CURL::

    curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001
    {
      "_runtime": 0.04700016975402832,
      "count": 2,
      "items": [
        {
          "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/latest-xkcd.png",
          "role": "SECONDARY",
          "filename": "latest-xkcd.png",
          "mimetype": "image/png",
          "size": 34230
        },
        {
          "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/Minto-Pyramid-Principle.pdf",
          "role": "SECONDARY",
          "filename": "Minto-Pyramid-Principle.pdf",
          "mimetype": "application/pdf",
          "size": 666021
        }
      ]
    }

Using jQuery::

    $.ajax({
        url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001",
        type: "GET"
    }).done(function (data) {console.log("file list: " + data.items); });

API: Get File Content
=====================

:URL: `files/:oid_or_number/:filename`
:method: `GET`

Returns the **file content** of the named file.

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

N/A -- this request returns the raw bytes of the file.

Examples
--------

http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt

or dynamically using jQuery::

    $.ajax({
        url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
        type: "GET"
    }).done(function (data) {console.log("file data: " + data); });

Or by just using the URL in e.g. a IMG tag::

    <img src="http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/latest-xkcd.png"
         alt="example" />

API: Create or update a file
============================

:URL: `files/:oid_or_number/:filename`
:method: `POST`

To **update** a file, issue a HTTP `POST` request to the URL of the file.
The *content* needs to be `base64` encoded, the author uses
`https://github.com/carlo/jquery-base64` for that.

To **create** a new file, just do the same, inventing a new filename url.

POST Data Format
----------------

The **POST** body must be a JSON data structure with the following format::

        {
            "data":         "<<data>>"
            "message":      "<< a check in message>>"
            "role":         "<<a winchill content role>>"
            "iterate":      True | False
        }

The data supplied needs to be base64 encoded.

The `role`, `iterate` and `message` values my optionally specified as
POST URL parameters.

**data**
    :default:  none
    :required: yes

    The base64 encoded data.

**message**
    :default:  "update file '<<name>>'"
    :required: no

    The message to use for the change made in the content holder.
    This message will show up in the standard Windchill UI.

**role**
    :default:  "SECONDARY"
    :required: no

    The content role to use.  For a list of valid content roles
    consult the Windchill Sys Admin Guide.  The most prominent ones
    are 'PRIMARY' and 'SECONDARY'.

**iterate**
    :default:  False
    :required: no

    If true, a new iteration is made automatically.

Response Data Format
--------------------

The response is a JSON encoded data structure with the following format::

    {
        "success": true|false,
        "oid":  <<the (possibly new) OID>>,
        "url": <<the URL to the file download>>
    }

Examples
--------

Using CURL::

   TBD

Using Python and the requests library::

   TBD

Using jQuery -- this assumes the base64 plugin for jQuery is installed::

    var data = "file content";
    $.ajax({
        url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
        type:     "POST",
        dataType: "json",
        contentType: "application/json",
        data:     JSON.stringify({ data: $.base64.encode(data) })
    }).done(alert("file updated"));

API: Delete a file
==================

:URL: `files/:oid_or_number/:filename`
:method: `DELETE`

To **delete** a file, issue a HTTP `DELETE` request to the URL of the file.

Response Data Format
--------------------

The response is a JSON encoded data structure with the following format::

    {
        "success": true|false,
        "oid":  <<the (possibly new) OID>>,
        "url": <<the URL to the file list>>
    }


Examples
--------

Deleting a file using jQuery::

    $.ajax({
        url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
        type: "DELETE"
    }).done(alert("file deleted"));


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