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.

Olfa BLEL
Parents
  • Hello, Thanks for the post that was very helpful especially for new comers to ARAS, i followed the explanation and i was able to do most of the actions (adding new item, deleting, retrieving existing items...), I'm trying to learn more and i have a situation:

    I work with a ItemType which has an action through right-click (The Action is associated with a method for sure !!)
    I have an existing Item let'scall it "Base_Item"of my ItemType i can right click on it chose the action Then the associated method is called and an new item is created based on some proprieties of "Base_Item"

    So How can use requests to call that action for an existing item?

  • Hi Oussama,

    Assuming that this Action uses a server-side method, you can follow the steps in this blog post to call that method on your item. 

    If the Action is using a client-side method, you won't be able to call it via the REST API as it is not aware of the Innovator Client.

    Chris

  • Hi Chris, Thank you for your answer

    I had a look at the post you mentioned when i was looking for some connecting points, but the Action is using a Client-side method in this case is there other solution to call it ?

    Oussama

  • 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

  • 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 ?

Comment Children
  • 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