ThingWorx REST API Cheat Sheet

    There is now an official REST API guide on the ThingWorx Developer Zone and there will me more to come int eh 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