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

Abstract
========

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

Purpose
=======

The purpose of the *number service* is to provide a high-level
programmer's API for accessing and manipulating **Windchill IBA** of
**EPMDocument Windchill Business Objects**.

Additionally, the API is able to set the numbers of **link objects** of
the *used* relation, if the root object is a `CADASSEMBLY` type.


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/numbers`

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


API URLs
--------

The following URLs define the API to the number service:

+------------------------------+--------+------------------+
| URL                          | Method | Purpose          |
+==============================+========+==================+
| numbers/version              | GET    | plug-in version  |
+------------------------------+--------+------------------+
| numbers/generate/:class-name | POST   | generate numbers |
+------------------------------+--------+------------------+


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

:URL: `version`
:method: `GET`

This fetches the *version* of the **number 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
-------

TBD -- curl example.

API: generate numbers
=====================

:URL: services/numbers/generate/:class-name
:Method: POST

A HTTP POST to this URL generates new numbers for the given class name.
The POST **MUST** contain either the `container-ref` or `container-name`
parameter, **OR** the `workspace-*` parameters.

**container-ref**
    :type: string

    The container reference OID

**container-name**
    :type: string

    The container name

**workspace-name**
    :type: string

    The name of an workspace to fetch the container reference from.

**count**
    :type: integer
    :default: 1

    How many numbers to generate.

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

The response is a JSON document with the following structure::

    {
      "count":           <<the count of new numbers generated>>
      "class_name":      <<the class name>>
      "container": {
        "oid":           <<the container reference OID>>
        "name":          <<the container name>>
      },
      "items":           <<an array of strings representing the numbers>>
    }

Examples
--------

Generate a number for a `wt.doc.WTDocument` type -- use initialization
rules from the *Drive System* container::

    $ curl --user wcadmin:Nexiles2013 -X POST http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/numbers/generate/wt.doc.WTDocument\?container-name\="Drive%20System"\&count\=1
    {
      "_runtime": 0.016000032424926758,
      "count": 1,
      "class_name": "wt.doc.WTDocument",
      "container": {
        "oid": "OR:wt.pdmlink.PDMLinkProduct:44295",
        "name": "Drive System"
      },
      "items": [
        "0000000049"
      ]
    }

Same as above, but generate **5** numbers, and specify the container by
it's reference OID::

    $ curl --user wcadmin:Nexiles2013 -X POST http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/numbers/generate/wt.doc.WTDocument\?container-ref\="OR:wt.pdmlink.PDMLinkProduct:44295"\&count\=5
    {
      "_runtime": 0.06200003623962402,
      "count": 5,
      "class_name": "wt.doc.WTDocument",
      "container": {
        "oid": "OR:wt.pdmlink.PDMLinkProduct:44295",
        "name": "Drive System"
      },
      "items": [
        "0000000050",
        "0000000051",
        "0000000052",
        "0000000053",
        "0000000054"
      ]
    }

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