Step 5: Add Property to Thing
Property values are associated with a specific Thing, and are used to store data that changes over time.
Required Parameters
- AppKey created by your ThingWorx server
- Name of the Thing to which the Property will be added
- Name for the new Property and data type of the Property's value
Request
- Construct the URL.
- A new Property can be added to an existing Thing by making an HTTP POST to this endpoint. Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server that will have the Property added.
<server_ip:port>/Thingworx/Things/<name of Thing>/Services/AddPropertyDefinition
2. Send request parameters.
- The name of the new Property to be added and type of the Property are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new Property named SomeNumber using the ThingWorx base type NUMBER. Some other commonly used types are STRING, INTEGER, and BOOLEAN.
{
"name" : "SomeNumber",
"type" : "NUMBER"
}
NOTE: The full request must include a header with the appKey for your specific ThingWorx server.
Response
A successful call to the AddPropertyDefinitionservice does not return any content in the body of the response. Only an HTTP 200 is returned.
HTTPie example:
http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddPropertyDefinition appKey==64b879ae-2455-4d8d-b840-5f5541a799ae name=SomeNumber type=NUMBER
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 AddPropertyDefinition 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 POST -d '{"name": "SomeNumber","type": "NUMBER"}' http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddPropertyDefinition?appKey=d0a68eff-2cb4-4327-81ea-7e71e26b
Validate
- View new Property on Server.
- The Property you just added is now available in the ThingWorx Composer. Before anything else can be done with your new Property through the REST API, the Thing must be restarted. To confirm your Property was added to your Thing, open Composer and click Things, select the name of the Thing you just created, then click Properties and Alerts. You will see the new Property listed. You may need to refresh to see the changes.
2. Execute RestartThing Service.
- Restart your Thing with the added Property by making a HTTP POST to the endpoint below. Substitute <name of Thing> with the actual name of the Thing you created. No body is required in the POST, however, the Content-Type header of a POST that executes a Service must always be set to application/json or text/xml even if the service does not take any parameters and no content is being sent. No body is returned upon success, only an HTTP 200 response code.
<server_ip:port>/Thingworx/Things/<name of Thing>/Services/RestartThing
HTTPie example:
http -v -j POST http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/RestartThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae
Step 6: Set Property Value
You can set the value of a specific Property with the REST API using the PUT verb.
Required Parameters:
- AppKey created by your Foundation server
- A Name of valid Thing and name of Property
- New Property value
Request
-
Construct the URL.
- A Property value can be set by making an HTTP PUT call to this endpoint:
<server_ip:port>/Thingworx/Things/<name of Thing>/Properties/<name of Property>
- Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server and <name of Property> with the name of a Property that has been added to the Thing.
2. Send request parameters.
- The name of the Property to be set is duplicated in the body of the PUT and is sent along with the value as a JSON object. The example below will set the Property SomeNumber to 34.4
{
"SomeNumber" : 34.4
}
NOTE: The full request must include authentication credentials for your specific ThingWorx server.
Response
A successful call to set a Property does not return any content in the body of the response. Only an HTTP 200 is returned.
HTTPie example
http -v -j PUT http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber appKey==64b879ae-2455-4d8d-b840-5f5541a799ae SomeNumber=34.4
WARNING for other HTTP clients: By default HTTPie sets the Accept and Content-type request headers to application/json. A PUT request to the Properties endpoint has a JSON body so the Content-Type header must be set to match the format of the request body.
Most HTTP clients do not set the correct header by default and it must be set explicitly. Below is an example cURL call that sets the Content-Type header to application/json
curl -v -H "Content-Type: application/json" -X PUT -d '{"SomeNumber":12.34}' http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber?appKey=d0a68eff-2cb4-4327-81ea-7e71e26b
Validate
To confirm your Property was changed for your Thing, go to Composer and click Things. Select the name of the Thing you just created, then click Properties and Alerts tab. Click on the circular arrow Refresh to see the updated Property value.
Step 7: Get Latest Property Value
You can retrieve Property values of a specific Thing with the REST API using the GET verb.
Required Parameters:
- AppKey created by your ThingWorx server
- Name of Thing and name of Property
Request
-
Construct the URL.
- To get the current value for a property, make a GET request to this endpoint:
<server_ip:port>/Thingworx/Things/<name of Thing>/Properties/<name of property>
Substitute <name of thing> with the actual name of a Thing that exists on the ThingWorx server and <name of Property> with the name of a Property that has been added to the Thing.
NOTE: The full request will also need to include the hostname and authentication credentials for your specific ThingWorx server.
2. Send request parameters. Other than authentication, no other parameters are used in this GET request.
Response
The content can be returned in four 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 |
HTTPie example:
http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber appKey==64b879ae-2455-4d8d-b840-5f5541a799ae
