Community Tip - You can subscribe to a forum, label or individual post and receive email notifications when someone posts a new topic or reply. Learn more! X
In order to execute a Service of a specific Thing with the REST API, you can use the POST verb.
Construct the URL.
<server_ip:port>/Thingworx/Things/<name of Thing>/Services/<name of Service>
Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server, and <name of Service> with an existing Service.
{ "firstNumber": "35", "secondNumber": "711" }
NOTE: The full request must include a header with the appKey for your specific ThingWorx server.
A successful call to a Service will return a JSON object in the body of the response containing both a DataShape object and an array named rows. Inside the array, an object named result will have the value returned by the custom Service. Here is an example response:
{ "dataShape": { "fieldDefinitions": { "result": { "aspects": {}, "baseType": "NUMBER", "description": "", "name": "result", "ordinal": 0 } } }, "rows": [ { "result": 746.0 } ] }
WARNING for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The POST request to the Service endpoint has a JSON body so the header must be set to match the format of the request body.
Collections of Entities that perform a function can be grouped then shared by exporting from a server. These entity collections are called Extensions and can be uploaded using the REST API. You can create custom Extensions or download Extensions created by other developers. You can use the REST API to automate the process of uploading an Extension to a ThingWorx server.
<Server IP:port〉Thingworx/ExtensionPackageUploader
X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE
A successful call to upload an Extension will return a description of the Entities that were successfully uploaded in the body of the response.
http -f POST iotboston.com:8887/Thingworx/ExtensionPackageUploader upload@/home/ec2-user/extension.zip X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645
curl -v --header X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE --header appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645 -F upload=@extension.zip iotboston.com:8887/Thingworx/ExtensionPackageUploader?purpose=import&validate=false
The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. The downloaded file can be imported to another ThingWorx server making the Thing available for use.
<Server IP:port>/Thingworx/Exporter/Things/<name of Thing>
It is possible for the content to be returned in two different formats by sending an Accept header with the request.
Desired Response Type |
Accept Header Values |
JSON | application/json |
XML | text/xml |
HTML | text/html (or omit Accept Header) |
CSV | text/csv |
A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server.
http -v GET iotboston.com:8081/Thingworx/Exporter/Things/PiThing appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml
The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. This file can be imported to another ThingWorx server making the Thing available for use.
<Server IP:port〉/Thingworx/Exporter/Things
searchTags
It is possible for the content to be returned in two different formats by sending an Accept header with the request.
Desired Response Type |
Accept Header Values |
JSON | application/json |
XML | text/xml |
HTML | text/html (or omit Accept Header) |
CSV | text/csv |
A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server
http -v GET iotboston.com:8081/Thingworx/Exporter/Things searchTags==Applications:Raspberry_light appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml
A Tag is composed of two parts: a Vocabulary, and a specific vocabulary term. A Tag is shown as Vocabulary:VocabularyTerm. Almost every ThingWorx entity can be tagged. Tags can be used to create a relationship between many different ThingWorx Entities.
You can use the REST API to create a new dynamic Tag vocabulary.
〈Server IP:port〉/Thingworx/ModelTags
{ "name": "SecondTest", "isDynamic": "true" }
A successful call to the ModelTag Service does not return any content in the body of the response, only an HTTP 200 is returned.
http -v -j PUT http://52.201.57.6/Thingworx/ModelTags name=SecondTest isDynamic=true appKey==64b879ae-2455-4d8d-b840-5f5541a799ae
Warning for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The PUT request to the ModelTags endpoint has a JSON body so the header must be set to match the format of the request body. The Content-Type header does not appear in the sample HTTPie call because HTTPie sets the Accept and Content-type request headers to application/json by default. Below is an example cURL call that explicitly sets the Content-Type header to application/json.
curl -v -H "Content-Type: application/json" -X PUT -d '{"name": "SecondTest", "isDynamic":"true"}' http://52.201.57.6/Thingworx/ModelTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645
You can use the REST API to add a Tag to a Thing. There must be a Thing and a Dynamic Tag Vocabulary already created on your Foundation Server before you can add a Tag.
〈Server IP:port〉/Thingworx/Things/〈name of Thing〉/Services/AddTags
{ "tags" : "SecondlightTest:RaspberryTest", }
A successful call to the AddTags Service does not return any content in the body of the response. Only an HTTP 200 is returned.
http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddTags appKey==64b879ae-2455-4d8d-b840-5f5541a799ae tags=SecondTest:RaspberryTest
curl -v -H "Content-Type: application/json" -X POST -d '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645
curl -v -H "Content-Type: application/json" -X POST -d '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645