Use REST API to Access ThingWorx Part 3

[#1]

• Step 8: Call Custom Service
• Step 9: Import and Export Entities
• Step 10: Authentication Tags

Step 8: Call Custom Service

In order to execute a Service of a specific Thing with the REST API, you can use the POST verb.

Required Parameters:

• AppKey created by your ThingWorx server
• Name of the Thing that implements a custom Service
• Name of the custom Service
• Names of inputs, if any, required by the Service

Request

1. Construct the URL.

   • To call a custom Service of an existing Thing, make an HTTP POST to this endpoint:

     <server_ip:port>/Thingworx/Things/<name of Thing>/Services/<name of Service>

     Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server, and <name of Service> with an existing Service.

2. Send request parameters
   • The names of the inputs along with their values are sent in the body of the POST as a JSON object. For example, the JSON object below will send a parameter named 'firstNumber' with a value of 35 and a parameter named secondNumber with a value of 711.

     {
     "firstNumber": "35",
     "secondNumber": "711"
     }

NOTE: The full request must include a header with the appKey for your specific ThingWorx server.

Response

A successful call to a Service will return a JSON object in the body of the response containing both a DataShape object and an array named rows. Inside the array, an object named result will have the value returned by the custom Service. Here is an example response:

{
    "dataShape": {
        "fieldDefinitions": {
            "result": {
                "aspects": {},
                "baseType": "NUMBER",
                "description": "",
                "name": "result",
                "ordinal": 0
            }
        }
    },
    "rows": [
        {
            "result": 746.0
        }
    ]
}

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 Service endpoint has a JSON body so the header must be set to match the format of the request body.

 

Step 9: Import and Export Entities

Collections of Entities that perform a function can be grouped then shared by exporting from a server. These entity collections are called Extensions and can be uploaded using the REST API. You can create custom Extensions or download Extensions created by other developers. You can use the REST API to automate the process of uploading an Extension to a ThingWorx server.

Required Parameters

• AppKey created by your Foundation server
• Path to properly formatted zip file containing extension Entities

Request

1. Construct the URL. Upload an Extension by making an HTTP POST to the endpoint:

<Server IP:port〉Thingworx/ExtensionPackageUploader

1. Send request parameters. The zip file that contains the extension entities is uploaded as a multi-part POST. The name of the file parameter is upload. Use a library to properly format the multi-part POST request You must also send this header:

X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE

1. Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...

 

Response

A successful call to upload an Extension will return a description of the Entities that were successfully uploaded in the body of the response.

HTTPie example:

http -f POST iotboston.com:8887/Thingworx/ExtensionPackageUploader upload@/home/ec2-user/extension.zip X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645

cURL example:

curl -v --header X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE --header appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645 -F upload=@extension.zip iotboston.com:8887/Thingworx/ExtensionPackageUploader?purpose=import&validate=false

 

Download Things By Name

The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. The downloaded file can be imported to another ThingWorx server making the Thing available for use.

Required Parameters

• AppKey created by your Foundation server
• Name of the Thing

Request

1. Construct the URL. Retrieve the components of a Thing by making an HTTP GET to the endpoint. Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server that wil be downloaded.

<Server IP:port>/Thingworx/Exporter/Things/<name of Thing>

1. Send request parameters. No parameters are sent.
2. Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...

 

Response

It is possible for the content to be returned in two 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

A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server.

HTTPie example:

http -v GET iotboston.com:8081/Thingworx/Exporter/Things/PiThing appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml

Download Things By Tag

The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. This file can be imported to another ThingWorx server making the Thing available for use.

Required Parameters

• AppKey created by your Foundation server
• Name of the Tag

Request

1. Construct the URL. Retrieve the components of a Thing by making an HTTP GET to the endpoint

<Server IP:port〉/Thingworx/Exporter/Things

1. Send request parameters. The Tag name is sent as a request parameter named:

searchTags

1. Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...

 

Response

It is possible for the content to be returned in two 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

A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server

HTTPie example:

http -v GET iotboston.com:8081/Thingworx/Exporter/Things searchTags==Applications:Raspberry_light appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml

 

 

Step 10: Authentication Tags

A Tag is composed of two parts: a Vocabulary, and a specific vocabulary term. A Tag is shown as Vocabulary:VocabularyTerm. Almost every ThingWorx entity can be tagged. Tags can be used to create a relationship between many different ThingWorx Entities.

Create New Tag

You can use the REST API to create a new dynamic Tag vocabulary.

Required Parameters

• AppKey created by your Foundation server
• Name of Tag Vocabulary

Request

1. Construct the URL. Create a new Tag Vocabulary by making an HTTP PUT to this endpoint:

〈Server IP:port〉/Thingworx/ModelTags

1. Send Request Parameters. The name of the new DataShape and the name of the base DataShape that the new DataShape extends are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new DataShape named SomeTestDataShape using the system template GenericThing.

    {
        "name": "SecondTest",
        "isDynamic": "true"
    }

1. Authenticate Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...

 

Response

A successful call to the ModelTag Service 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/ModelTags name=SecondTest isDynamic=true appKey==64b879ae-2455-4d8d-b840-5f5541a799ae

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 PUT request to the ModelTags 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 PUT -d '{"name": "SecondTest", "isDynamic":"true"}' http://52.201.57.6/Thingworx/ModelTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645

 

Add Tag to Thing

You can use the REST API to add a Tag to a Thing. There must be a Thing and a Dynamic Tag Vocabulary already created on your Foundation Server before you can add a Tag.

Required Parameters

• AppKey created by your Foundation server
• Name of the Thing to be tagged
• Name of Dynamic Tag Vocabulary
• Name of for Tag to be assigned to Thing

Request

1. Construct the URL. Substitute 〈name of Thing〉 with the actual name of a Thing that exists on the ThingWorx server that will have the Tag added. Add a new Tag to an existing Thing by making an HTTP POST to this endpoint:

〈Server IP:port〉/Thingworx/Things/〈name of Thing〉/Services/AddTags

1. Send request parameters. The name of the new field to be added and type of the field are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new field named SomeNumber using the ThingWorx base type NUMBER. Some other commonly used types are STRING, INTEGER, and BOOLEAN. Include a header in the full request with the appKey for your specific ThingWorx server.

    {
        "tags" : "SecondlightTest:RaspberryTest",
    }

 

Response

A successful call to the AddTags Service 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/AddTags appKey==64b879ae-2455-4d8d-b840-5f5541a799ae tags=SecondTest:RaspberryTest

curl -v -H "Content-Type: application/json" -X POST -d '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645

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 '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645

 Click here to view Part 4 of this guide.