=============== API Description =============== :Author: Stefan Eletzhofer :Date: |today| :State: **production** Abstract ======== This is a description of the **attribute service**. Purpose ======= The purpose of the *attribute 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 attributes 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: `<>:<>/<>/servlet/nexiles/tools/services/attributes` 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/attributes/version API URLs -------- The following URLs define the API to the attribute service: +-------------------------------------------+--------+------------------+ | URL | Method | Purpose | +===========================================+========+==================+ | attributes/version | GET | plug-in version | +-------------------------------------------+--------+------------------+ | attributes/:number_or_oid | GET | list attributes | +-------------------------------------------+--------+------------------+ | attributes/:number-or-oid/:unique-link-id | POST | set attributes | +-------------------------------------------+--------+------------------+ | attributes/:number-or-oid/:unique-link-id | DELETE | clear attributes | +-------------------------------------------+--------+------------------+ .. note:: The 'unique-link-id' is a number which uniquely identifies a link object **for the current iteration/version only** API: Version ============ :URL: `version` :method: `GET` This fetches the *version* of the **attribute 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: List Attributes ==================== :URL: services/attributes/:number_or_oid :Method: GET Fetches the attributes of the **EPMDocument** given it's *OID* or *number*. If a URL parameter `links=yes` is passed, then all the attributes of the component links are fetched, too. Example using jQuery, underscore and CoffeeScript:: $.getJSON '/Windchill/servlet/nexiles/tools/services/attributes/GETRIEBE.ASM', (data) -> console.log "We got #{data.count} attributes" _.each data.items (value, key) -> console.log "#{key} = #{value}" if key isnt "id" API: Set Attributes =================== :URL: services/attributes/:number_or_oid :Method: POST Set some attribute values. .. note:: The **EPMDocument** needs to be *checked out* for any modifications. Example using jQuery, underscore and CoffeeScript. This would set the attributes `DESCRIPTION` and `NORM` on the component link with id `42` of the **EPMDocument** with number `GETRIEBE.ASM`:: # suppose we got this ID from a previous GET link_id = 42 attributes = DESCRIPTION: "This part frobnicates the whizbang" NORM: "DIN0815/4711 42x13" req = $.ajax url: "/Windchill/servlet/nexiles/tools/services/attributes/GETRIEBE.ASM/#{link_id}' type: "POST" req.done (data) -> if data.success console.log "successfully set attributes: #{data.items}" API: Clear Attributes ===================== :URL: services/attributes/:number_or_oid :Method: DELETE Clear some attribute values. .. note:: The **EPMDocument** needs to be *checked out* for any modifications. Example using jQuery, underscore and CoffeeScript. This would **clear** the attributes `DESCRIPTION` and `NORM` on the component link with id `42` of the **EPMDocument** with number `GETRIEBE.ASM`:: # suppose we got this ID from a previous GET link_id = 42 attributes = DESCRIPTION: "does not matter" NORM: "does not matter" req = $.ajax url: "/Windchill/servlet/nexiles/tools/services/attributes/GETRIEBE.ASM/#{link_id}' type: "DELETE" req.done (data) -> if data.success console.log "successfully cleared attributes: #{data.items}" .. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: