ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > REST Web Services and WS EMS > Updating, Deleting, and Executing with REST Web Services
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
Sample URL
HTTP Action
Content Type
Updates require specifying the entity part (“thing_name” in the sample)
application/json or text/xml
Deletes require specifying the entity part as well
Calling a service requires specifying the complete URL, including the specific characteristic
If your service requires them, these inputs should be passed in the form fields of your POST.
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:
Supported HTTP Methods
Retrieve a value.
Write a value or create new things or properties.
Execute a service.
Delete a thing or property.
For Content Type
In Accept Header, Use
text/html (or omit Accept header)
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 see it, this information must be shown as JSON.
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 WS 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 WS EMS/LSR, the WS 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 unauthorized. 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 WS EMS and LSR as of v.5.4.2, see Running REST API Calls with Postman on WS EMS and LSR.