Use REST API to Access ThingWorx Part 4
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
- 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
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...
- 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 |
| JSON | application/json |
| XML | text/xml |
| HTML | text/html (or omit Accept Header) |
| CSV | text/csv |
HTTPie example:
http -v -j http://52.201.57.6/Thingworx/Users appKey==64b879ae-2455-4d8d-b840-5f5541a799ae Accept:text/csv
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 Code | Definition |
| 401 - Unauthorized | appKey is incorrect or missing |
| 403 - Forbidden | Content-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 Found | Incorrect URL or API endpoint Thing or Property has not been created Incorrect ThingTemplate name Required parameter missing from request |
| 405 - Invalid Request | Incorrect request verb; for example a GET was used instead of PUT or POST |
| 406 - Not Acceptable | Invalid JSON in PUT or POST request Thing [ Thing name ] already exists: A Thing with that name already exists on the platform |
| 500 - Internal Server Error | Content-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 Unavailable | Thing [] 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:
| Capability | Guide |
| Build | Data Model Introduction |
Additional Resources
If you have questions, issues, or need additional information, refer to:
| Resource | Link |
| Community | Developer Community Forum |
| Support | REST API Help Center |