.. _tut-low-level-api: ============================== Tutorial: Low Level API Access ============================== :Author: Stefan Eletzhofer :Date: 2012-05-22 Abstract ======== This tutorial chapter discusses how to use the low-level API object. Prerequisites ------------- - You should be comfortable using the **python REPL**. - You should have at least read the :ref:`tut-introduction` and :ref:`tut-queries`. Why A Low Level API? ==================== - There'll be always some API calls which will not be wrapped in utility functions. - This API is used by the other, higher level functions - By understanding the low level API, you gain a better understanding how the API works. - Because we can ;) Overview ======== You can access the API using the API objects which you get by :py:func:`nexiles.tools.api.get_api` and :py:func:`nexiles.tools.api.get_resource`. API Call Results ---------------- All API calls return a *Python mapping* object Specific Resources ~~~~~~~~~~~~~~~~~~ Calls to a specific resource return a mapping like this:: >>> from nexiles.tools.api import get_api, get_resource >>> api = get_api(...) >>> resource = get_resource(api, "document") >>> resource("OR:....") { "description": "desc", "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043176", "oid": "OR:wt.doc.WTDocument:149043176", "modified": "2012-05-04T13:48:11", "number": "246B7CC974E5498DAC670FD5307A562B", "item": { ... more keys ... }, "version": "-.1", "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:149043176&u8=1", "name": "TestDoc" } The idea is that the *top level* keys are *generic*, that is, available for **all** resources: **url** The **URL** to the object which produces the output. **oid** The **OID** of the object **number** The **number** of the object. **details** The Windchill UI `details` page for this object. This is **not** a API URL. If available, these keys are added, too: **name** The **name** of the object. **cadname** The **cadname** of the object -- i.e. the *file name*. Only for **EPM Documents**. **description** The description. **version** The version of *iterable* items. **path** The **path** of *folderable* items. **path** The **path** of *folderable* items. **modified** The **modified** timestamp. The `items` key itself is a mapping which contains keys highly specific to a business object. Queries ~~~~~~~ **Queries** return lists of items. Example:: >>> resource.get(limit=4) { "count": 4, "items": [ { "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043432", "oid": "OR:wt.doc.WTDocument:149043432", "number": "0000000481", "name": "foo" }, { "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149047649", "oid": "OR:wt.doc.WTDocument:149047649", "number": "0000000441", "name": "bar" }, { "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149049620", "oid": "OR:wt.doc.WTDocument:149049620", "number": "00000000482", "name": "baz" }, { "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335", "oid": "OR:wt.doc.WTDocument:147270335", "number": "0000000461", "name": "quux" } ] } Here, we **always** include the `count` key on the top level. This holds the number of results. The **items** key holds a *sequence* of mappings, one mapping for each result. These mappings contain keys: **url** The **URL** to the resource. **oid** The **OID** of the result. **number** The **name** of the result. **name** The **name** of the result. Common Tasks ============ .. note:: For the following examples we assume that the *local* variable `oid` holds the OID of a specific object which exists in the Windchill database. Getting IBA Attributes ---------------------- Accessing the `IBA Attributes` of a business object in Windchill is done by accessing the `attributes` action on a specific object:: >>> resource = get_resource(api, "document") >>> result = resource(oid).attributes.get() >>> print result { "count": 1, "description": "desc", "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043573", "items": [ { "name": "CUSTOMER", "value": "nexiles" } ], "oid": "OR:wt.doc.WTDocument:149043573", "modified": "2012-05-06T16:57:23", "number": "5F03E86A98E84ECABE5F7977C4D63590", "version": "-.1", "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:149043573&u8=1", "name": "TestDoc" } This is a **query**, so we need to check for the `count` attribute:: >>> count = result["count"] >>> attributes = result["items"] Now we have all the attributes in `attributes`. This is now a list of mappings, each having a `name` key, and a `value` key:: >>> print attributes[0] { "name": "CUSTOMER", "value": "nexiles" } Getting the iteration or version history ---------------------------------------- Accessing the `history` of a business object in Windchill is done by accessing the `history` action on a specific object:: >>> resource = get_resource(api, "document") >>> results = resource(oid).history.get(q="iterations") >>> print results { "count": 2, "description": "", "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335", "items": [ { "description": "", "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335", "oid": "OR:wt.doc.WTDocument:147270335", "number": "0000000461", "modified": "2012-05-03T19:50:14", "version": "-.2", "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147270335&u8=1", "name": "foo" }, { "description": "", "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147213032", "oid": "OR:wt.doc.WTDocument:147213032", "number": "0000000461", "modified": "2012-05-03T18:36:26", "version": "-.1", "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147213032&u8=1", "name": "foo" } ], "oid": "OR:wt.doc.WTDocument:147270335", "modified": "2012-05-03T19:50:14", "number": "0000000461", "version": "-.2", "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147270335&u8=1", "name": "foo" } This is a **query**, so we need to check for the `count` attribute:: >>> count = results["count"] >>> iterations = results["items"] Now we have all the iterations in `iterations`. For all the *versions*, just pass `q="versions"`:: >>> results = resource(oid).history.get(q="versions") The processing of the `results` is the same as above. Getting Help ------------ All the `actions` which are available can be listed like so:: >>> help_items = resource(oid).help.get().get("items") The help items will each contain a `url`, `docstring`, `name` and `http_method` attribute. .. note:: the above is best *viewed* using a browser which is able to format **JSON** documents nicely. For *chrome* and *firefox*, install the **JSONView** plugin. To display the `help` for a `document`, navigate to: http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:..../help You need to replace the `OID` and the base URL of course. .. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: