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.

Sumit Jaiswal
  • Hello Chris,

    I am able to do CRUD operation for Manufacturer, Manufacturer Part and Part but I was not able to perform the PATCH or POST operation on state of the Manufacturer , Manufacturer Part and Part.

    Example : Manufacturer will be in Preliminary state should be moved to Approved state, I need to do automatically by using REST API from the tool how it can be done. I need explanation please.

  • I was able to create all the CRUD operation successfully on part, manufacturer, manufacturer part but I was not able to update or PATCH the STATE from Preliminary to Approved state using the PATCH or POST please input some idea on this.

    How can I PATCH the existing state of the Manufacturer, Manufacturer Part and Part respectively.

  • It is not possible to call a client-side methods from the server in any way. The distinction can be tricky, so I'll explain why that it is.

    The Server does not know anything about the client. It gets a request via AML or the REST API that says "run this action on this item". That request could be coming from the Innovator client or some external application. The Server makes no distinction here and will run the action regardless of where the request is coming from.

    Client methods on the other hand are expected to be called only from the Innovator client. Lets take a simple example where a client method has a couple lines of code to open a new tab for a given Item. A server could also have many different Innovator clients connected to it at the same time. If client methods were able to called from the server, which client should the new tab be opened in? What if there were no clients actively connected at that time?

    If your existing client-side code does not do anything specific to the Innovator client like opening a new tab, it should be simple to convert it to server-side code instead. In general, it's good practice to only use Client methods for code that specifically interacts with the client for exactly this reason. Server-side methods can be re-used anywhere that you want to call them.

    Chris

  • Hi Chris,

    Before i start migrating the method to the server side iwas thinking of a "primitive solution",can we creat a server side methode wich calls the client-side method ?

  • Hi Oussama,

    Depending on what this action is doing, you may be able to migrate the functionality into a server method instead. This would be your best bet as Client-side methods are not available to call via the REST API.

    Chris