Updating, Deleting, and Executing with REST Web Services
The following rules help to understand what is needed based on the type of request being made.
|
Requested Action
|
Notes
|
Sample URL
|
HTTP Action
|
Content Type
|
|---|---|---|---|---|
|
UPDATE
|
Updates require specifying the entity part (“thing_name” in the sample)
|
http://host/Thingworx/Things/thing_name/
|
PUT
|
application/json or text/xml
|
|
DELETE
|
Deletes require specifying the entity part as well
|
http://host/Thingworx/Things/thing_name
|
DELETE
|
n/a
|
|
INVOKING SERVICES
|
Calling a service requires specifying the complete URL, including the specific characteristic
|
http://host/Thingworx/Things/MyThing/Services/myService
If your service requires them, these inputs should be passed in the form fields of your POST.
|
POST
|
application/json
|
Executing HTTP Requests
When executing HTTP requests, use UTF-8 encoding, and specify the optional port value if required.
 |
Use HTTPS in production or any time network integrity is in question.
|
Handling HTTP Response Codes
In most cases, you should expect to get back either content or the status code of 200, which indicates that the operation was successful. In the case of an error, you receive an error message.
Working with HTTP Content
If you are sending or receiving any HTTP content (JSON, XML, HTML [for responses only]), set the request content-type header to the appropriate value based on the HTTP content you are sending. The following table lists and briefly describes the HTTP methods that are supported:
|
Use
|
To
|
|---|---|
|
GET
|
Retrieve a value.
|
|
PUT
|
Write a value or create new things or properties.
|
|
POST
|
Execute a service.
|
|
DELETE
|
Delete a Thing or property.
|
|
For Content Type
|
In Accept Header, Use
|
|---|---|
|
JSON
|
application/json
|
|
XML
|
text/xml
|
|
HTML
|
text/html (or omit Accept header)
|
Metadata
You can display the metadata of any specific Thing, Thing Template, or Data Shape you build by going to the following URL in a web browser: NameoftheThing/Metadata
 |
To view it, this information must be in JSON format.
|
Passing in Authentication with your REST Web Service Call
To authenticate with the ThingWorx Platform for a REST Web Service call, use an application key that is associated with a user account that has the privileges to perform the actions that you intend to invoke, using the REST Web Services. If the HTTP Server configuration for your EMS has authentication enabled, you need to include your credentials in basic authentication form.
|
|
Although you can pass in a username and password combination with your REST call, the recommended best practice is to use an application key. Generate the key in ThingWorx Composer and then pass it with your REST call. The user account associated with the application key should have privileges to read/write properties and run services on the related devices/machines in the ThingWorx Platform.
|
If you pass in a user name and password, note that username and password are Base64 encoded in the Authorization Header. As the delimiter symbol is a ":" (colon) between username and password (e.g. "ptc:ptc") the username must not contain a ":" (colon) character. Otherwise, the requests will fail with an error message, HTTP 401 Status - Authentication Required .
CSRF Tokens and REST Web Service Calls
When CSRF tokens are enabled, you need to add certain header values to your requests. Upon the first successful authenticated request from the client to the EMS/LSR, the EMS/LSR returns a response that includes a random CSRF token in the x-csrf-token header The client must include this token in any subsequent PUT, POST, or DELETE requests, or those requests are rejected as not authenticated. This token value may be changed, or ‘rotated’, at a defined interval.
For more information about using the REST services in Postman and the CSRF token support provided in the REST API for EMS and LSR as of v.5.4.2, refer to Running REST API Calls with Postman on EMS and LSR.