Today we're going to learn how to use the Axeda Platform SDK v2 APIs to upload a file to the platform and create a software package. This document is a work in progress, but we're going to show you everything you need to get started. In my case I am using the very useful and easy to use Postman REST Client app available from the Chrome Store. I'll be using some terms below (API Object Names) that can be found in the documents listed in the bibliography at the end of this article.
Assumptions (Replace these with your own versions):
- username: joe, password: password1!
- platform instance: axedaplatform.example.com
First things first, we need to authenticate to the platform and get a session id (header x_axeda_wss_sessionid).
(Note: Postman does not automatically URL encode query parameters - this can be especially important for the password)
You'll receive a response like this following:
<ns1:WSSessionInfo xmlns:ns1="http://type.v1.webservices.sl.axeda.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:WSSessionInfo">
<ns1:created>2015-06-02T15:16:49 +0000</ns1:created>
<ns1:expired>false</ns1:expired>
<ns1:sessionId>1a5XXXXX-d9aa-47f2-ac4f-28765ce5dbc5</ns1:sessionId>
<ns1:sessionTimeout>1800</ns1:sessionTimeout>
</ns1:WSSessionInfo>
Excellent, now we have a session id!
For the rest of the API calls (unless otherwise indicated), all of the following headers are set to the following:
- x_axeda_wss_sessionid: 1a5XXXXX-d9aa-47f2-ac4f-28765ce5dbc5
- Content-Type: application/xml
- Accept: application/xml
The next step is to get our ModelReference:
POST: https://axedaplatform.example.com/services/v2/rest/model/findOne
<?xml version="1.0" encoding="UTF-8"?>
<ModelCriteria xmlns="http://www.axeda.com/services/v2">
<modelNumber>MyModelName</modelNumber>
</ModelCriteria>
Which will return output like:
<v2:Model xmlns:v2="http://www.axeda.com/services/v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="MyModelName" systemId="6141" label="managed" detail="MyModelName"
restUrl="https://sandbox.axeda.com/services/v2/rest/model/id/6141">
<v2:name>MyModelName</v2:name>
<v2:modelNumber>MyModelName</v2:modelNumber>
<v2:autoRegisterAssets>false</v2:autoRegisterAssets>
<v2:type>MANAGED</v2:type>
...
</v2:Model>
The key piece of information we need from that request is the systemId.
A little bit about our file (lorem-ipsum.txt):
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla.
- File-size: 307
- MD5 Sum: 22b229c7ecc49cfa11255beb06c7f4fe
The next step is to create a FileUploadSession and upload our file. This will create for us the FileInfoReference we need to create our SoftwarePackage.
PUT: https://axedaplatform.example.com/services/v2/rest/file/session
BODY:
<?xml version="1.0"?>
<FileUploadSession xmlns='http://www.axeda.com/services/v2'>
<files>
<file xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:type='FileInfo'>
<filename>lorem-ipsum.txt</filename>
<md5>22b229c7ecc49cfa11255beb06c7f4fe</md5>
<filesize>307</filesize>
<contentType>application/text</contentType>
</file>
</files>
<expirationDate/>
<status/>
<updatedDate/>
<username/>
<version/>
</FileUploadSession>
And our response if all goes OK (HTTP 200) looks like the following:
<v2:ExecutionResult xmlns:v2="http://www.axeda.com/services/v2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" successful="true" totalCount="1">
<v2:succeeded>
<v2:success xsi:type="v2:FileUploadSessionSuccessfulOperation">
<v2:ref>16265</v2:ref>
<v2:id>16265</v2:id>
<v2:uploadUri>sftp://DISABLED</v2:uploadUri>
<v2:session systemId="16265" label="16265" detail="16265"
restUrl="https://sandbox.axeda.com/services/v2/rest/file/id/16265">
<v2:files>
<v2:file xsi:type="v2:FileInfo" id="1068731" systemId="1068731"
label="lorem-ipsum.txt" detail="1068731">
...
</v2:success>
</v2:succeeded>
</v2:ExecutionResult>
In this case, we just need the value of <v2:file systemId>, which is 1068731.
TIME TO UPLOAD THE FILE CONTENTS!!!
PUT: https://axedaplatform.example.com/services/v2/rest/file/1068731/content/
Extra Headers:
- X-File-Name: lorem-ipsum.txt
- X-File-Size: 307
- Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
BODY: There needs to be a mime-part called 'file-content' that contains the contents or lorem-ipsum.txt
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file-content"; filename="cfk-lorem-ipsum.txt"
Content-Type: text/plain
----WebKitFormBoundary7MA4YWxkTrZu0gW
Note: If using Postman, SoapUI or other automated tool, this will be handled automatically for you - do not specify a Content-Type header in this case.
And our response, assuming an HTTP 200:
<v2:ExecutionResult xmlns:v2="http://www.axeda.com/services/v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" successful="true" totalCount="1">
<v2:succeeded>
<v2:success>
<v2:ref>1068731</v2:ref>
<v2:id>1068731</v2:id>
</v2:success>
</v2:succeeded>
<v2:failures />
</v2:ExecutionResult>
This is just confirming our success! Excellent. Now we come to the SoftwarePackage. We need two key pieces of information, the ModelReference (6141) and the FileInfoReference (1068731):
POST: https://axedaplatform.example.com/services/v2/rest/softwarePackage
Headers: Our defaults, Content-Type and x_axeda_wss_sessionid
BODY:
<?xml version="1.0" encoding="UTF-8"?>
<SoftwarePackage xmlns="http://www.axeda.com/services/v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<name>TEST-REST-PACKAGE</name>
<model systemId="6141" />
<version>1.0.0.1</version>
<primaryAgentsOnly>true</primaryAgentsOnly>
<retriesEnabled>true</retriesEnabled>
<instructions>
<instruction xsi:type="DownloadFileInstruction">
<file xsi:type="FileInfo" systemId="1068731"/>
<destinationDirectory>C:\temp</destinationDirectory>
<compressed>false</compressed>
<executable>false</executable>
<pathRelative>false</pathRelative>
<overwriteExistingEnabled>true</overwriteExistingEnabled>
</instruction>
</instructions>
</SoftwarePackage>
And our results:
<v2:ExecutionResult xmlns:v2="http://www.axeda.com/services/v2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" successful="true" totalCount="1">
<v2:succeeded>
<v2:success>
<v2:ref>TEST-REST-PACKAGE||1.0.0.1</v2:ref>
<v2:id>45863</v2:id>
</v2:success>
</v2:succeeded>
<v2:failures />
</v2:ExecutionResult>
And PROOF!
I hope this helps you in your projects, and helps demystify the Axeda Platform REST API a little for you.
Regards,
-Chris
Bibliography (Documents available from Support Portal):
- Axeda v2 API/Services Developer's Reference Guide_6.8
- Axeda Platform Web Services Developer Reference v2REST_6.8
Change History:
2015-09-24 : Change HTTP Methods of session create and content send to PUT from POST
Hi,
I am following your instructions,
1. I have created FileUploadSession successfully
2. Now try to upload file content, it block me - HTTP 200 returned but no message returned..
So I don't know what happened and is there something wrong.
Below is my request body,
On the body tab, instead of raw, pick "form-data".
Then choose the example file, and give it the key "file-content" and set the type to "File".
Regards,
-Chris Kaminski
PTC/Axeda Customer Support
Hi Chris - I see this older thread has been marked as Resolved but I'm hoping you'll be able to assist me. If I need to open a case with PTC please let me know and I will do so. I'm trying to create a package using this exact example you gave. Step 1, 2, 3 are fine. I can get a session Id, my model Id, and File Upload session id (6219 in my example):
Step 4: I think I am uploading the contents of the file successfully because if I purposely use the wrong MD5 I get an error. I also tried different file sizes. The larger file takes a bit longer. So I think the file is uploading ok. However, the response is not complete, like in your example:
Again, I'm not sure step 4 is completely successful, but I'll move on to step 5. I get a 404 error, resource not found.
Clearly I'm doing something wrong but I can't figure it out. I'm confident the model id is 794 (screenshot below from step 2). Will you please provide me with some guidance?
Thanks, Mike Grudinschi
