Community Tip - Want the oppurtunity to discuss enhancements to PTC products? Join a working group! X
There is now an official REST API guide on the ThingWorx Developer Zone and there will be more to come in the future as we update our documentation/guides/tutorials/etc.
Good starting point for learning about ThingWorx REST APIS
http://support.ptc.com/cs/help/thingworx_hc/thingworx_7.0_hc/
The following sections will be useful to you for general reference:
-ThingWorx REST API
-ThingWorx Platform API Documentation
Get a list of services on a specific thing
Using the following GET request you can get a list of all available service on a given thing. If done through your browser, then you will be able to click on each individual service to learn more about the parameters needed.
${platform}/Thingworx/Things/${thingName}/serviceDefinitions
All of these services can be executed via the REST API using the following format: ${Platform}/Thingworx/Things/${thing name}/Services/${add service and query parameters here}.
NOTE: the same thing can be done on other entities such as ThingTempaltes or Thing Shapes by replacing the "Things/${thing name}" part with "ThingTemplates/${thing template name}" or "ThingShapes/${thing shape name}" etc.
Entity Services:
EntityServices is a resource that allows you to control the typical Create, Read, Update and Delete (CRUD) services for all entities ont eh platform. Using the method listed above, you canget a list of all available services using the following REST call:
${platform}/Thingworx/Resources/EntityServices/ServiceDefinitions
Each of these services can be executed using the following endpoint structure: ${Platform}/Thingworx/Resources/EntityServices/Services/${service name}.
NOTE: any of the methods listed with "/Services/" as part of the URL you can find a matching service through Composer (ThingWorx UI) in the "services" section for a given thing or resource. You can execute many different services this way.
API call Examples:
All of the following API calls will be preceded with the following:
https ://{your ThingWorx host here}/Thingworx/
Note: in order to use appKeys instead of basic auth, you will need the following query parameters in your calls:
?appKey={your appkey}&x-thingworx-session=true
List Things:
NOTE: The same can be done for any other entity type on the platform
Method: Get
URL: /Things
Headers: Accept: “application/json”
Expected Response:
Status Code: 200
Example Response Body:
...
"rows":
{
"isSystemObject": true
"name": "MyThing1"
"description": "some description"
"homeMashup": "MonitoringAlertHistory"
"avatar": "/Thingworx/Things/MyThing1/Avatar"
"tags": []
}
{
"isSystemObject": false
"name": "MyThing2"
"description": "another description"
"homeMashup": ""
"avatar": "/Thingworx/Things/MyThing2/Avatar"
"tags": []
}
...
Create Thing:
NOTE: After creating a thing you will need to enable then restart it in order to use it. Those calls are listed next.
Method: POST
URL: /Resources/EntityServices/Services/CreateThing
Content-Type: "application/json"
Post Body:
{
"name":{name of the thing to create},
"description":{description for the thing you are creating}
"thingTemplateName":{name of the template to base the thing on, can use
"GenericThing" if there is not a specialized template}
}
example:
{
"name": "myThing",
"description":"thing description",
"thingTemplateName":"GenericThing"
}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Enable Thing:
Method: POST
URL: /Things/{Thing Name}/Services/EnableThing
Content-Type: "application/json"
Post Body:
{}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Restart Thing:
Method: POST
URL: /Things/{Thing Name}/Services/RestartThing
Content-Type: "application/json"
Post Body:
{}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Add Property Definition:
Method: POST
URL: /Things/{ThingName}/Services/AddPropertyDefinition
Content-Type:"application/json"
Post Body: NOTE: There are many different inputs you can have for this, these are the simple ones that are likely all you will need
{
"name":{name of your property},
"description":{description of this property},
"type":{type of the property, must be a valid type such as "STRING" or "NUMBER"},
}
Example Post Body:
{
"name": "myProperty",
"description":"This is a String Property",
"type":"STRING"
}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Get All Property Values:
Method: GET
URL: /Things/{ThingName}/Properties
Accept:"application/json"
This will return json formatted information about the thing, you will want the values under "rows"
Expected Response:
Status Code: 200
Example Response Body:
...
rows:
[
{
"myProperty": "test"
"name": "myThing"
"description": "property description"
"thingTemplate": "GenericThing"
"tags": []
}
]
Get Single Property Value:
Method: GET
URL: /Things/{ThingName}/Properties/{property name}?appKey={appKey}
Accept:"application/json"
This will return json formatted information about the thing, you will want the values under "rows"
Expected Response:
Status Code: 200
Example Response Body:
...
rows:
[
{
"myProperty": "test"
}
]
Set Property Values:
Method: PUT
URL: /Things/{ThingName}/Properties/{propertyName}
Content-Type:"application/json"
Post Body:
{
{name of property}:{value of property}
}
Example Post Body:
{
"myProperty":"test"
}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Add Event Definition:
Method: POST
URL: /Things/{ThingName}/Services/AddPropertyDefinition
Content-Type:"application/json"
Post Body:
{
"name":{name of the event},
"description":{description of the event},
"dataShape":{data shape on the platform to use for event information, this needs to exsist ahead of time}
}
Example Post Body:
{
"name": "myEvent",
"description": "This event triggers when a tag moves out of a given zone",
"dataShape": "3DZoneShape"
}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Trigger Event:
Method: POST
URL: /Things/{ThingName}/Events/{name of event to trigger}
Content-Type:"application/json"
Post Body:
{json formatted data that matches the field for your defined dataShape}
Example Post Bodies:
1. Empty dataShape:
{}
2. Example dataShape with zone and time:
{
"Zone":3,
"Time":"4/6/2016 10:31:15"
}
Expected Response:
Status Code: 200
Example Response Body:
No Body
Thank you Dan for sharing!
Hi Dan,
Can I create a thing and enable it using a single API? Like both Thing Creation and Enabling should be done at a time.
Hi Babu,
A little late to the party, but the answer is yes, if you create a service on the ThingWorx side and wrap those internal calls inside it.
Best regards,
There is a reason to have this separated. This gives you the flexibility to make changes to the thing and connect subscriptions and events BEFORE the Thing get active. Therefore you can avoid a thing executing on an incomplete definition. Therefore a method that do this all and at the end enable the thing will wrap all these and make it at the end only ONE call to create a new Thing.
Hi Everyone My Requirement is bit different
I want to Pass Parameters from Webpage to Thingworx Mashup. To Explain In detail
I have a webpage designed by ASP.NET here i am integrating Thingworx Mashup in Iframe control.
So my Webpage have Asp.control and Thingworx mashup.
In below screen i have integrated Thingworx mash up in iframe.
When i select drop down (Asp.net Control ) the selected value should pass to thingworx mashup. and mashup should respond accordingly.
I need to know the process how we can pass values from Asp.net web page thingworx Mashup.
Looking for Positive Response.
If any clarification in understanding requirement i will post in detail.
Thanks
spandhana
Hi Spandhana,
I am no mashup expert, but my understanding is that mashups only interact with the Thingworx back end and passing through a value directly to the mashup is no possible. That being said, you can always make traditional API calls to the Thingworx server top change values that the mashup relies on in order to have the mashup change in response to it. For example, if you are setting a property on the mashup, you can have the mashup get the property then directly set it through the Thingworx API. Hope this helps.
Also, if you did end up opening a separate thread on this issue, please link to it here so the question and responses all route to it.
Hi Dan, could you add an example of setting a property of type LOCATION through rest? Not sure what the format is since it is a compound value.
HI Vladimir,
This document is no longer being updated as there is now a guide on the developer zone (mentioned at the top of this page). One thing I have found however to help in scenarios like this is to use the chrome developer console to see what value is sent when setting a value for something like this through composer. In this scenario, when using this method I get:
{location: {latitude: "2.3", longitude: "1.4", elevation: "0", units: "WGS84"}}
when setting the value of a property named "location" and calling /Things/thingName/properties with a PUT
Hope this helps
Hi Dan, thanks for info. Take care that the link is no longer valid, https://developer.thingworx.com/guides/thingworx-rest-api-quickstart gives a 404.
Thanks both, I fixed the link
for Add Event Definition, I think the URL was wrote the wrong word
Correct should be "URL: /Things/{ThingName}/Services/AddEventDefinition"
Add Event Definition:
Method: POST
URL: /Things/{ThingName}/Services/AddPropertyEventDefinition
Content-Type:"application/json"
Post Body: