ThingWorx REST API Cheat Sheet
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