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
