cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Learn all about the Community Ranking System, a fun gamification element of the PTC Community. X

Use REST API to Access ThingWorx Part 4

No ratings

 

Step 11: Users

 

Access to functions and information on the ThingWorx Foundation server is controlled by Users. The REST API can be used to create, list, and delete Users.

 

Get Usernames of all Users

 

The REST API exposes the ability to retrieve collections of Entities so that a UI can be dynamically updated with current data.

 

Required Parameters

 

  • AppKey created by your Foundation server

Request

 

  1. Construct the URL. Include the hostname and authentication credentials for your specific ThingWorx server as described below. The Usernames of all Users can be returned by making a GET request to this endpoint:
    〈Server IP:port〉/Thingworx/Users
  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...

  2. Send request parameters. Other than authentication, no other parameters are used in this GET request.

Response

 

It is possible for the content to be returned in four different formats by sending an Accept header with the request.

 

Desired Response Type
 Accept Header Values
JSONapplication/json
XMLtext/xml
HTMLtext/html (or omit Accept Header)
CSVtext/csv

 

HTTPie example:

 

http -v -j http://52.201.57.6/Thingworx/Users appKey==64b879ae-2455-4d8d-b840-5f5541a799ae Accept:text/csv
 

Get_users_csv.png

 

 

Step 12: Troubleshooting

 

You should expect to get back the status code of 200 - OK either with or without content. In the case of an error, you will receive an error message. You can use the following table to diagnose the issue.

 

Response CodeDefinition 
401 - UnauthorizedappKey is incorrect or missing
403 - ForbiddenContent-Type request header is not set to application/json
Sometimes returned instead of a 404
A Property with that name already exists on the platform
404 - Not FoundIncorrect URL or API endpoint
Thing or Property has not been created
Incorrect ThingTemplate name
Required parameter missing from request
405 - Invalid RequestIncorrect request verb; for example a GET was used instead of PUT or POST
406 - Not AcceptableInvalid JSON in PUT or POST request
Thing [ Thing name ] already exists: A Thing with that name already exists on the platform
500 - Internal Server ErrorContent-Type request header is not set for a service execution POST, required even without a POST body
Content-Type request header is not set for DELETE request, required despite the fact that DELETE does not send any content
503 - Service UnavailableThing [] is not running
RestartThing endpoint must be called
Thing [] is not enabled
EnableThing endpoint must be called

 

 

 

Step 13: Authentication Tags

 

There are different ways to authorize requests.

 

AppKey in HTTP Request Header

 

We recommend you place the appKey in the HTTP request header rather than passing the appKey as a URL parameter. This prevents the appKey from being written into server log files that may be seen by someone who is not authorized to modify the ThingWorx server.

 

HTTPie example:

 

http -v -j http://iotboston.com:8887/Thingworx/Things/aTestThing/Properties/CurrentTemp appKey:d0a68eff-2cb4-4327-81ea-7e71e26

Full request headers:

 

GET /Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Type: application/json
Host: iotboston.com:8887
appKey: d0a68eff-2cb4-4327-81ea-7e71e26bb

 

AppKey In URL as Parameter

 

To send an appkey in a URL request string parameter, check the Allow Application Key as URL Parameter checkbox in the PlatformSubsystem Configuration. If the ThingWorx server is using HTTPS, the parameter will be encrypted in transit, however the appKey may be comprised because full request URLs are often written to server log files.

 

HTTPie example:

 

http -v -j http://iotboston.com:8887/Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645

Full request headers:

 

GET /Thingworx/Things/aTestThing/Properties/CurrentTemp?appKey=d0a68eff-2cb4-4327-81ea-7e71e26 HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Type: application/json
Host: iotboston.com:8887

 

HTTP Basic Auth

 

We do not recommend Basic Auth, because the username and password used are NOT encrypted and could be used to log into the ThingWorx platform. To demonstrate that username and password are not encrypted, copy the string in the Authorization line after Basic to Base64 Decode then click DECODE.

 

HTTPie example:

 

http -v -j http://iotboston.com:8887/Thingworx/Things/aTestThing/Properties/CurrentTemp -a Administrator:password1

Full request headers:

 

GET /Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE=
Connection: keep-alive
Content-Type: application/json
Host: iotboston.com:8887
 
 

Step 14: Next Steps

 

Congratulations! You've successfully completed the Use REST API to Access ThingWorx guide.

You learned how to use the REST API to:

 

  • Create new Things on a ThingWorx Foundation Server
  • Add Properties to Things
  • Access Property values
  • Execute custom Services

 

The next guide in the Connect and Configure Industrial Devices and Systems learning path is Java SDK Tutorial.

 

Learn More

 

We recommend the following resources to continue your learning experience:

 

 
 CapabilityGuide
BuildData Model Introduction

 

Additional Resources

 

If you have questions, issues, or need additional information, refer to:

 


Resource   Link
CommunityDeveloper Community Forum
SupportREST API Help Center

 

 
Version history
Last update:
‎Nov 18, 2022 04:21 PM
Updated by:
Labels (2)
Contributors