Tech Tip: Using the Aras RESTful API

Tech Tip: Using the Aras RESTful API

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.

[caption id="attachment_11439" align="alignnone" width="1420"] Screenshot shows the required headers entered in the Postman client.[/caption]

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.

[caption id="attachment_11440" align="alignnone" width="2473"] Get all Parts using the OData request url "http://{server}/{web alias}/server/odata/Part".[/caption]

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.

[caption id="attachment_11441" align="alignnone" width="2473"] Create a new Part with the "POST" HTTP action and required properties in the request body.[/caption]

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.

[caption id="attachment_11442" align="alignnone" width="1703"] Updating Part number P-00033 to fix the item_number property.[/caption]

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.

[caption id="attachment_11499" align="alignnone" width="1700"] Deleting a Part by id.[/caption]

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.

  1. Back up your code tree and save the copy in a safe place.
  2. Open IIS on the server.
  3. In the Connections pane, navigate to the Server sub-application of your Aras Innovator instance.
  4. In the Features View list, double click Modules.
  5. Select the WebDAVModule module.
  6. In the Actions pane, click Remove.
  7. 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.