Community Tip - Did you get called away in the middle of writing a post? Don't worry you can find your unfinished post later in the Drafts section of your profile page. X
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.
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.
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 |
The ThingWorx REST API uses HTTP request verbs in ways common to many REST APIs:
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.
The following tables describe the valid Accept and Content-Type header values when making a REST API calls.
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 |
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 |
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:
NOTE: The following steps in this guide use Httpie as the client software.
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.
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.
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.
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.
An HTTP POST request to ThingWorx is assembled from 3 components:
1. Construct the URL.
<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.
{ "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.
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
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 -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
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.
2. Execute EnableThing Service.
<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.
<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