Using the Ingestion API

Note: The following content uses Postman as an example and you may need to adapt it to the API client of your choice.

A sample API collection is included in the Postman Collection for Ingestion API appendix.

Install API Client

When using the Ingestion API, install the required API client on to your local machine.

If you already have an API client installed, you can import the attached collection and start making the API calls.

Importing the API collection

Import the attached collection (refer the sample topic Postman Collection for Ingestion API ) into the API client.

For example, you can use https://learning.postman.com/docs/getting-started/importing-and-exporting-data/ as a reference documentation on how to use Postman.

Sending data to the Data Pipeline (Ingestion API)

Execute the following API calls by providing the required parameters as described below in the order defined:

Init API

1. Select Init API call from the imported API client's collection.

2. Replace {Ingestion-API-Base-URL} with the Ingestion API URL you have received from AVEVA.

3. Select the Authorization tab.

4. From the Type dropdown list, select Bearer Token.

5. Provide the actual CONNECT Token instead of the {token} value.

   

6. Switch to the Body tab.

7. Provide the actual AIM-A CONNECT Folder Name instead of {AIM-A CONNECT Folder Name} as the assetId.

   

8. Select Send once all the parameters are in place.

   You receive the transactionId as a response if the call is successful.

Upload URI API

9. Select Upload URI API call from the imported API client's collection.

10. Replace {Ingestion-API-Base-URL} with the Ingestion API URL that you have received from AVEVA.

    This URL should also be included in your firewall rules.

11. Select the Authorization tab.

12. From the Type dropdown list, select Bearer Token.

13. Provide the actual CONNECT Token instead of the {token} value.

    

14. Select the Headers tab.

15. Provide the transaction ID returned by the Init call as the transactionId.

    

16. Switch to the Body tab.

17. Provide the set of API parameters based on the type of data you want to load and the type of processing it requires. Refer to the Ingestion API Request Parameters appendix for more details on these parameters. These parameters are different for different types of data so read through the referenced documentation. You can provide an array of files as a part of this request.

    

18. Select Send once all the parameters are in place.

19. As a response, you get one upload URL for each file in the API request. You can put the actual file against these URLs directly.

Uploading the Class library

To upload a class library, you need to use the following set of body parameters in the Upload URI request:

[{

"target": "CL",

"fileName": "clib.xml"

}]

Uploading data

To upload data, you need to use the specific set of body parameters in the Upload URI request. These parameters are defined based on the type of files, refer to the Ingestion API Request Parameters appendix for more details on these parameters. Examples have been included for each type of file.

Put File into Upload URL

20. Copy the upload URL for the file from the Upload URL API response.

21. Open the PUT API Call from the imported API client's collection.

22. Paste the upload URL in the address bar instead of {Url-Returned-By-Upload-Url-API-call}.

23. Switch to the Body tab.

24. Select binary as the request type. Select Select File and select the file to be uploaded.

    

25. Select Send and wait for an OK response (Response Code - 200) to be displayed.

26. These steps need to be repeated for all the files that you initially requested upload URLs for.

Complete API

27. Select the Complete API call from the imported API client's collection.

28. Replace {Ingestion-API-Base-URL} with the Ingestion API URL that has been received from AVEVA.

29. Select the Authorization tab. From the Type dropdown list, select Bearer Token.

30. Provide the actual CONNECT Token instead of the {token} value.

    

31. Select the Headers tab. Provide the transaction ID returned by the Init call as the transactionId.

    

32. Switch to the Body tab.

33. Set status to completed.

    

34. Select Send once all the parameters are in place.

35. If successful, a count of files that have been uploaded is confirmed in the response. If the number of files is greater than 100, an identifier -ge to denote the number of files uploaded are more than 100 is received.

Firewall Whitelisting

Some organizations have IT restrictions that mandate any external connection to be whitelisted in the firewall settings. In case your organization has any such whitelisting policy, you must whitelist the following URLs based on the region your AIM-A instance is provisioned in. The first URL is the regional Ingestion API endpoint. The second URL is the file upload URL. Both URLs must be whitelisted to successfully upload data.

Note: If you are still using the old Ingestion API URLs, you must whitelist the respective URLs mentioned in the table above (as internally the old URL still calls these endpoints). For example:

• Old Ingestion URL: https://ingestionapi.imav.connect.aveva.com

• Old Upload URL: https://aveva-regi-orchestration-aimaprod.s3-accelerate.amazonaws.com