Aras Innovator 11 SP12 introduced a RESTful API that can be used to query and edit Aras items. Most of the time, these REST calls will be sent to the Aras server by an external application or integration. You can find a sample AngularJS app that uses the new Aras RESTful API on the Aras Labs GitHub page. However for the purpose of this blog post I’ll be using the popular API development environment, Postman, to demonstrate some common REST calls. Postman is a handy tool for testing API calls without writing any code.
Setting Up the Call
A successful API call to Aras Innovator requires four key pieces of information. First, you need the url for your Innovator instance’s OData service: http://{server}/{web alias}/server/odata. For brevity, we’ll call this the “base url” in this post.
You also need to include the following headers for authenticating the request:
- DATABASE: The database you want to connect to
- AUTHUSER: The Innovator user name you want to use to connect
- AUTHPASSWORD: The MD5 hashed password for the AUTHUSER
In Postman, you can add the headers to your request under the “Headers” tab.
Important Note!
The AUTHUSER used in the request header will be used when evaluating user permissions in Aras Innovator. If you try getting or editing items that the AUTHUSER does not have permission to get or edit, you will receive an error or “No items of type {ItemType} found” in the call’s response. Similarly, if you hard-code the root or admin user as shown in this blog, you may inadvertently expose data that not all users should be able to get and edit.
Getting Items
The most simple GET call retrieves a collection of all items in an ItemType. For example, I can retrieve all Parts using GET http://{server}/{web alias}/server/odata/Part.
Of course, you may not want to get all properties for all items of an ItemType. There are a few different ways you can query item data:
Retrieve a single item by id
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity", "classification": "Component", "created_on": "2018-03-20T19:37:02", "description": "Part 2 description", "generation": "1", "has_change_pending": "0", "id": "F45F259F527942EB8A6C4011BC784EF0", "is_current": "1", "is_released": "0", "keyed_name": "P-00002", "major_rev": "A", "make_buy": "Make", "modified_on": "2018-03-20T19:37:02", "name": "Part 2", "new_version": "0", "not_lockable": "0", "state": "Preliminary", "unit": "EA", "item_number": "P-00002" }
Filter items on criteria
GET {base url}/Part?$filter=item_number eq ‘P-00001’
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part", "value": [ { "classification": "Component", "created_on": "2018-03-20T19:36:06", "description": "Part 1 description", "generation": "1", "has_change_pending": "0", "id": "FE186527EB6B40079EE0334AD47B353A", "is_current": "1", "is_released": "0", "keyed_name": "P-00001", "major_rev": "A", "make_buy": "Make", "modified_on": "2018-03-20T19:36:06", "name": "Part 1", "new_version": "0", "not_lockable": "0", "state": "Preliminary", "unit": "EA", "item_number": "P-00001" } ] }
Select specific properties
GET {base url}/Part?$select=id,item_number,name
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part(id,item_number,name)", "value": [ { "id": "FE186527EB6B40079EE0334AD47B353A", "item_number": "P-00001", "name": "Part 1" }, { "id": "F45F259F527942EB8A6C4011BC784EF0", "item_number": "P-00002", "name": "Part 2" }, { "id": "16AA95A80DEB4B56BD8BA9BC509EAF0C", "item_number": "P-00033", "name": "Part 3" }, { "id": "836DB08EB33D412EB662D75934CADCF1", "item_number": "Part-00005", "name": "Test Part 5" } ] }
Count the resulting items
GET {base url}/Part/$count
4
Get a property value
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)/item_number/$value
P-00002
Get an item property’s data
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)?$expand=created_by_id&$select=item_number
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part(item_number)/$entity", "@odata.id": "Part('F45F259F527942EB8A6C4011BC784EF0')", "item_number": "P-00002", "created_by_id": { "created_on": "2002-04-24T13:46:12", "generation": "1", "id": "30B991F927274FA3829655F50C99472E", "is_current": "1", "is_released": "0", "keyed_name": "Innovator Admin", "last_login_date": "2018-03-22T12:56:04", "login_name": "admin", "logon_enabled": "1", "major_rev": "A", "modified_on": "2004-01-16T20:18:31", "new_version": "0", "not_lockable": "0", "state": "Released", "working_directory": "C:", "first_name": "Innovator", "last_name": "Admin" } }
Get relationships / related items
GET {base url}/Part(‘C3F13FE4A2674B9691A6B311B5CCBCDB’)/Part CAD?$expand=related_id
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part CAD", "value": [ { "behavior": "hard_fixed", "created_on": "2018-03-26T21:23:54", "generation": "1", "id": "A732D5425B0F4362BA48062BACA1C7F4", "is_current": "1", "is_released": "0", "keyed_name": "A732D5425B0F4362BA48062BACA1C7F4", "major_rev": "A", "modified_on": "2018-03-26T21:23:54", "new_version": "1", "not_lockable": "0", "related_id": { "created_on": "2018-03-26T21:23:30", "generation": "1", "has_change_pending": "0", "id": "B1ABC9872FF2440A9909E9D34A5AF363", "is_current": "1", "is_released": "0", "is_standard": "0", "is_template": "0", "keyed_name": "CAD-00002", "major_rev": "A", "modified_on": "2018-03-26T21:23:30", "name": "CAD for P-00002", "new_version": "1", "not_lockable": "0", "state": "Preliminary", "item_number": "CAD-00002" }, "sort_order": "128" } ] }
Creating Items
To create new items in Aras Innovator, use the “POST” HTTP action and include the new item’s properties in the request body.
Create a new item
POST {base url}/Part
Body:
{ "item_number": "Part-00005", "name": "Test Part 5" }
Result:
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity", "created_on": "2018-03-20T20:24:49", "generation": "1", "has_change_pending": "0", "id": "836DB08EB33D412EB662D75934CADCF1", "is_current": "1", "is_released": "0", "keyed_name": "Part-00005", "major_rev": "A", "make_buy": "Make", "modified_on": "2018-03-20T20:24:49", "name": "Test Part 5", "new_version": "0", "not_lockable": "0", "state": "Preliminary", "unit": "EA", "item_number": "Part-00005" }
Create a new item in property (deep insert)
POST {base url}/Part
Body:
{ "item_number": "Part-00006", "name": "Test Part 6", "owned_by_id": { "name": "New Identity" } }
Response:
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity", "created_on": "2018-03-26T21:45:28", "generation": "1", "has_change_pending": "0", "id": "8CAD376AC9284307A1299695FAC40F8F", "is_current": "1", "is_released": "0", "keyed_name": "Part-00006", "major_rev": "A", "make_buy": "Make", "modified_on": "2018-03-26T21:45:29", "name": "Test Part 6", "new_version": "0", "not_lockable": "0", "owned_by_id": { "created_on": "2018-03-26T21:45:29", "generation": "1", "id": "41D69C4C75BF4512942E0368385B3A26", "is_alias": "0", "is_current": "1", "is_released": "0", "keyed_name": "New Identity", "major_rev": "A", "modified_on": "2018-03-26T21:45:29", "new_version": "1", "not_lockable": "0", "name": "New Identity" }, "state": "Preliminary", "unit": "EA", "item_number": "Part-00006" }
Editing Items
To update an Aras item, use the “PATCH” HTTP action and include any properties you want to update in the body of the request. Be sure only to include updatable properties, or the request will fail.
Update an item
PATCH {base url}/Part(’16AA95A80DEB4B56BD8BA9BC509EAF0C’)
Body:
{ "item_number": "Part-00003" }
Response:
{ "@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity", "classification": "Assembly", "created_on": "2018-03-20T19:37:43", "description": "Part 3 description", "generation": "2", "has_change_pending": "0", "id": "7F7556DE8ED642A6BE78C43259A00087", "is_current": "1", "is_released": "0", "keyed_name": "Part-00003", "major_rev": "A", "make_buy": "Make", "modified_on": "2018-03-26T21:51:58", "name": "Part 3", "new_version": "0", "not_lockable": "0", "state": "Preliminary", "unit": "EA", "item_number": "Part-00003" }
Deleting Items
To delete an item using the Aras RESTful API, you can use the “DELETE” HTTP action. Be sure to include the id of the item you want to delete.
Delete an Item
DELETE {base url}/Part(‘C3F13FE4A2674B9691A6B311B5CCBCDB’)
Both the request body and response are empty when deleting an item. Note that you can only delete one item at a time.
405.0 – Method Not Allowed Error
Did you get a 405 HTTP error when trying to delete an item from Innovator? This may happen if the WebDAV module in an out-of-the-box installation conflicts with the RESTful API. To resolve this error, you can try the following steps.
- Back up your code tree and save the copy in a safe place.
- Open IIS on the server.
- In the Connections pane, navigate to the Server sub-application of your Aras Innovator instance.
- In the Features View list, double click Modules.
- Select the WebDAVModule module.
- In the Actions pane, click Remove.
- Click “Yes” to confirm.
LOOKING FOR MORE ARAS INSPIRATION?
Subscribe to our blog and follow @ArasLabs on Twitter for more helpful content! You can also find our latest open-source projects and sample code on the Aras Labs GitHub page.