cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Need to share some code when posting a question or reply? Make sure to use the "Insert code sample" menu option. Learn more! X

ThingWorx REST API Cheat Sheet

danme
5-Regular Member

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

12 REPLIES 12
ankigupta
5-Regular Member
(To:danme)

Thank you Dan for sharing!

bkanipakam-2
4-Participant
(To:danme)

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.

sdaram
1-Newbie
(To:danme)

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

danme
5-Regular Member
(To:danme)

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.

danme
5-Regular Member
(To:danme)

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.

jebeck
6-Contributor
(To:danme)
danme
5-Regular Member
(To:danme)

Thanks both, I fixed the link

LeslieKuo
13-Aquamarine
(To:danme)

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:

Top Tags