Leverage the REST API to create Things, modify Properties, execute Services and more.
GUIDE CONCEPT
This project will introduce you to the REST API utilized by the ThingWorx platform.
Following the steps in this guide, you will be able to connect to the ThingWorx platform and make REST calls to call Services, update Properties, and perform a number of actions for your IoT applications.
We will teach you how to use the ThingWorx REST API to create a more robust application. With the REST API you can leverage the full power of the ThingWorx Foundation server with simple HTTP requests. The REST API can easily be explored using a command line tool such as curl, a browser plugin like Postman, or any preferred programming language.
YOU'LL LEARN HOW TO
Create new Things on a ThingWorx Foundation Server
Add Properties to Things
Access Property values
Execute custom Services
NOTE: The estimated time to complete ALL 4 parts of this guide is 30 minutes.
Step 1: REST API Design
Almost every Entity and Service of ThingWorx can be accessed through the REST API. This step will review some points that are common to all ThingWorx REST API calls.
REST API Syntax
The endpoint URLs used by the REST API follow the consistent pattern shown in the diagram below.
The following table describes the individual pieces of the URL for the REST API calls.
Term
Description
Optional/Required?
http method
GET, PUT, DELETE, POST
required
scheme
http, https
required
host
server IP address where ThingWorx is running
required
port
port on which the Web Server is listening for requests (default is 80)
optional
entity collection
One of the built-in entity collection types proprietary to ThingWorx
required
entity
name that identifies a specific characteristic
required
characteristic collection
Names such as Property Definition, Properties VTQ, ThingName, and Service Definition
optional
characteristic
name of the Service or Property on which to execute
optional
accept header
format of HTTP content being requested; must be application/json or text/xml or text/html
optional
content type header
format of HTTP content being provided; must be application/json, text/csv or text/html
required
content
optional
query parameters
optional
Requests
The ThingWorx REST API uses HTTP request verbs in ways common to many REST APIs:
GET to retrieve information
POST for both creating a new entity and executing a service
DELETE to remove a Thing or Property
PUT to change the value of an existing entity
When a REST API request requires parameters to be sent, the Content-Type header must be set to match the format of the request body.
Discovering and using Services requires using a dedicated URL. To list available Services and see their definitions, issue a GET to
```
<server_ip:port>/Thingworx/Things/<name of thing>/ServiceDefinitions
```
In order to execute a listed Service issue a POST to
```
<server_ip:port>/Thingworx/Things/<name of thing>/Services/<service name>
```
NOTE: The Content-Type header of a POST that executes a Service must always be set to application/json or text/xmleven if the service does not take any parameters and no content is being sent.
Responses
The following tables describe the valid Accept and Content-Type header values when making a REST API calls.
Accept Headers
If the request sends either an invalid Accept header, or no Accept header is supplied, the default response will be in text/html format.
Value
Syntax
JSON
application/json
XML
text/xml
HTML
text/html (or omit Accept header)
CSV
text/csv
Content Type Headers
A Content-Type header indicating the format of data sent to ThingWorx, is required. Some POST requests require a content type header even when no data is being sent.
Value
Syntax
JSON
application/json
XML
text/xml
Step 2: REST Client
In order to make calls to any REST API you need a client software. A web browser can be used to make some GET calls, but you must install extensions to modify headers or to make POST or PUT calls.
Client software options include:
cURL is a venerable command line tool and library that is a Swiss Army Knife of dealing with web requests. And like an old Swiss Army Knife you can make it work but you might wind up hurting yourself.
Httpie is a modern command line tool with easy to use, intuitive options. Server responses are shown in color with easy to read formatting. The examples will be given as HTTPie commands.
NOTE: The following steps in this guide use Httpie as the client software.
Step 3: Create Application Key
In this Quickstart, you will use ThingWorx Composer to generate an Application Key.
A device must be authenticated to send data to, or recieve data from ThingWorx. One of the most common authentication methods used with ThingWorx is by using a security token called an Application Key or appKey. These tokens are associated with a particular user and have the same permissions as that user.
Create an Application Key
On the Home screen of Composer click + New.
In the dropdown list, click Applications Key.
Give your Application Key a name (ie, MyAppKey).
Set the User Name Reference to a User you created.
Update the Expiration Date field, otherwise it will default to 1 day.
Click Save.
A Key ID has been generated and can be used to make secure connections.
BEST PRACTICE: We recommend you create separate keys for every connected device, User or system. This allows better security in case of situations where you may need to revoke access from one of them.
Step 4: Create New Thing
A Thing is a basic building block used to model applications in the ThingWorx Foundation Server. All Things are based on a Thing Template, either a built-in system template or a custom Template that was previously created. With the REST API, you can create, modify, list, and delete Things. After a Thing has been created by using an API call, it must be enabled and restarted with additional API calls before it can be used.
Required Parameters
AppKey created by your ThingWorx server
A name for the new Thing
The name of a valid ThingTemplate that will be used to create the new Thing
Request
An HTTP POST request to ThingWorx is assembled from 3 components:
a URL
A POST body
Authentication credentials A request to ThingWorx can be made only after these 3 components are properly configured.
1. Construct the URL.
Create a new Thing by making an HTTP POST to the endpoint.
<server_ip:port>/Thingworx/Resources/EntityServices/Services/CreateThing
NOTE: The server_ip is the ip address of your ThingWorx Core server.
2. Required POST body parameters.
Send the name of the Thing and the name of the ThingTemplate that will define the new thing in the body of the POST as a JSON object. For example, the JSON object below will create a new Thing named SomeTestThing using the system template GenericThing.
{
"name": "SomeTestThing",
"thingTemplateName": "GenericThing"
}
TIP: When creating Things that will be used with the REST API, use the GenericThing ThingTemplate or a ThingTemplate based GenericThing. A RemoteThing should only be used with devices that make an AlwaysOn™ connection to a ThingWorx server using the Edge MicroServer or one of the AlwaysOn™ SDKs.
3. 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...
Refer to Step 13: Authentication Tags for an overview of different authentication methods.
Response
A successful call to the CreateThing service does not return any content in the body of the response, only an HTTP 200 is returned.
Examples
HTTPie example:
http -v http://52.201.57.6/Thingworx/Resources/EntityServices/Services/CreateThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae name=SomeTestThing thingTemplateName=GenericThing
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.
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 CreateThing endpoint has a JSON body so the header must be set to match the format of the request body.
cURL example
curl -v -H "Content-Type: application/json" -X POST -d '{"name": "SomeTestThing","thingTemplateName": "GenericThing"}' http://52.201.57.6/Thingworx/Resources/EntityServices/Services/CreateThing?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645
Note: cURL explicitly sets the Content-Type header to application/json.
Validate
The Thing you just created is now available in the ThingWorx Composer, however before anything else can be done with your new Thing through the REST API it must be enabled and started. Follow these steps to validate that the new Thing has been created and enabled.
From the home page of Composer, click Things, select the name of the Thing you just created, then click General Information.
NOTE: You will see the Active checkbox is not checked indicating this Thing is not Enabled.
2. Execute EnableThing Service.
To enable your newly created Thing, make an 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/EnableThing
HTTPie example
http -v -j POST http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/EnableThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae
3. Confirm new Thing is Enabled.
To update the General Information section of your new Thing and confirm the Active checkbox is now checked, refresh the page with the browser or close and re-open your Thing.
4. Restart your Thing.
After a Thing is created and whenever any changes are made to its structure, the Thing has to be restarted. Start you new Thing 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
Click here to view Part 2 of this guide
View full tip
