Use REST API to Access ThingWorx Part 1

[#1]

• GUIDE CONCEPT
• Step 1: REST API Design
• Step 2: REST Client
• Step 3: Create Application Key
• Step 4: Create New Thing

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

1. On the Home screen of Composer click + New.
   
   

2. In the dropdown list, click Applications Key.
   
   

   

3. Give your Application Key a name (ie, MyAppKey).
   
   

4. Set the User Name Reference to a User you created.
   
   

   

5. Update the Expiration Date field, otherwise it will default to 1 day.
   
   

6. 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.

1. 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