Wednesday, 14 September 2016

Acumatica REST API

HI All,

With Acumatica 6 release you can find (and actually use) new type of API - Rest API.

Acumatica Rest API is based on Contract based API, so here you have some important points:

  • You need to use existing or custom endpoint be able to send API calls
  • Field and container is available for REST API only if it is defined in contract. But you may extend existing contracts.
  • With REST API you have the same set of commands that you have with Contract Based API.
  • Acumatica uses Json format for transfer data between client and server
  • You still have to maintain session and authentication cookies.

URL:
http://<InstanceName>/entity/<EndpointName>/<EndpointVersion>/<Entity>
Example: http://acumatica.com/entity/Default/6.00.001/StockItem

Ok, lest try to do some examples. Here I will show you how to call Acumatica REST commands from Browser. By using this approach you can easily test functionality and just feel, how does it work.


To do so, we need a special tool. I will use PostMan extension for Google Chrome browser.
As we need to maintain session and cookies between calls, we also need to install Postman Interceptor extension.


Login
Now we actually can login. To do so, we need to send our credentials for the specific url:

URL: http://acumatica.com/entity/auth/login
JSON data:
{
    "name" : "admin",
    "password" : "123",
    "company" :  ""
}
Response should be 204 No Content.


Geting
Ok, authentication is done, lets try to select data.

URL: http://acumatica.com/entity/Default/6.00.001/StockItem



Filtering
If we want some filtering or conditions, we just can use "OData" like filters - $filter=ItemStatus eq 'Active'

URL: http://acumatica.com/entity/Default/6.00.001/StockItem?$filter=ItemStatus eq 'Active'&$top=9

Additional parameters that you can use together with URL when you retrieve records from Acumatica ERP:
  • $filter: To specify filtering conditions on the records to be returned
  • $skip: To specify the number of records to be skipped from the list of returned records
  • $top: To specify the number of records to be returned in the list
  • $expand: To specify the linked and detail entities to be expanded
  • $custom: To specify the fields that are not defined in the contract to be returned

Getting Single Record
If you know key, you can easily get details about single record - just add key field to the url string:

URL: http://acusea.acumatica.com/future/entity/Default/6.00.001/StockItem/AACOMPUT01


Puting
You also can create new entity using REST API, in this case you need to use PUT method and send item details using JSON format. Name of the fields and containers you can get from Contract definition.

URL: http://acusea.acumatica.com/future/entity/Default/6.00.001/StockItem

JSON:
{
"InventoryID" : {value : "Kettler" } ,
"Description" : {value : "New Cool Kettler" },
"ItemClass" : {value : "ELECCOMP" }
}


Documentation
Good news that the documentation on the REST API is included right within standard Acumatica Help. There you can find multiple examples and good code snippets that you can use from your favorite language/platform/code.


Have a nice integration!

No comments: