REST Web Services Supported by EMS
The EMS is built to reflect the ThingWorx REST Web Service, but it is not a complete reflection. Rather, it is reflection of those Web Services that are most useful at the Edge. For example, if you try to look at Resources, nothing is returned. If you try to look at properties for a Thing that either is running the EMS or that is registered with it (EMS is running as a gateway), you can view all the properties. By default, the EMS returns data in JSON format.
For example, these Web Services do work with an EMS:
• /Thingworx/Things/thing_name/Properties
• /Thingworx/Things/thing_name/Properties/prop_name
where thing_name represents the name of any device that is connected to the local EMS where you are using a REST Web Service, and prop_name represents the name of any property for the specified device.
 |
As of v.5.4.2, support for CSRF tokens has been added to the REST API for EMS and LSR. It is enabled by default. Before using the REST API, be sure to read CSRF Token Support.
|
Browser-based Use of REST Web Services
The REST Web Services of the ThingWorx Platform can be used in a browser or an application that supports the HTTP commands. However, the behavior of the REST Web Services on an EMS is slightly different.
You cannot use a PUT through a query parameter of the REST Web Service in a browser, as on a ThingWorx Platform. For example, the following use of PUT works on a platform, but not on an EMS:
https://<server_ip/Thingworx/Things/<thing_name>/Properties/<property_name>/
method=put&<prop_name>=<value>
You actually must do an HTTP PUT to the EMS, using a REST client that can do an HTTP PUT.
Another difference with the ThingWorx REST Web Services lies in how an EMS returns the information for a specific property. Both ThingWorx and an EMS use an infotable to return the information. However, an EMS returns the rows first and the Data Shape second. This order is the opposite from the order in which the ThingWorx REST Web Services return the information.
Similarly, for services, the following use of a service such as GetDescription works on a ThingWorx Platform, but not on an EMS:
https://<server_ip>/Thingworx/Things/thing_name/Services/GetDescription
For EMS, you must request to run services by using a POST through a client that can do an HTTP POST.
|
|
You cannot send POST commands using a web browser if CSRF tokens are enabled (enabled by default and strongly recommended to keep enabled). You must use POSTMAN or another REST client.
|
As long as you do not have any input parameters for the service and if CSRF tokens are not enabled (strongly discouraged), you could do it this way from a browser:
https://localhost:8000/Thingworx/Things/thing_name/Services/GetDescription/method=POST
However, if you have parameters and leave CSRF tokens enabled, use a client that can do an HTTP POST.
Here are a few of the REST Web Services of the ThingWorx that do not work with EMS:
• /Thingworx/Things
• /Thingworx/Things/thing_name
• /Thingworx/Resources
By default, an EMS uses application/json for the Accept header.
|
|
As of v.5.4.2, support for CSRF tokens has been added to the REST API for EMS and LSR. It is enabled by default. Before using the REST API, be sure to read CSRF Token Support in REST API for EMS and LSR.
|
Using a REST Client with an EMS
You can use a REST client such as Postman to run REST Web Services against an EMS. You can save them and even set up collections of them. In addition, you can export a collection and import them into a Javascript engine such as Node.js.
|
|
Before using Postman, be sure to read Running REST API Calls with Postman on EMS and LSR and in particular, the section, CSRF Token Support in REST API for EMS and LSR.
|
When you are using REST Web Services, it is important to set your headers correctly:
• Accept — Specifies the format in which the data should be returned — JSON for EMS. For ThingWorx Platform, you can also choose XML or text.
• Application key (appKey) — Provides the authentication you need with the platform. You do not need it when running a REST Web Service against a local EMS.
Although the application key is strongly recommended when running a REST Web Service against a remote EMS, you can use basic authentication. In Postman, you can select Basic Authorization and specify a user name and password to access the ThingWorx Platform.
• x-thingworx-session — Determines if your request will set up an HTTP session with the ThingWorx instance. Having a session makes it possible to send multiple requests from a browser to ThingWorx Composer without having to authenticate with each request. When you set up a session, the browser and Composer authenticate each request in the background.
However, in an application, you do not want a session because sessions take up memory. For an application, set this header to false so that the ThingWorx Platform does not create a session every time that the application sends a request. Sending the appKey with each request does not impact memory.
|
|
If you use Basic authentication, you always get a session with the ThingWorx Platform. With an application, use an appKey for authentication and set the x-thingworx-session header to false.
|
• x-csrf-token — A random string used for Cross-Site Request Forgery (CSRF) protection in the EMS. When authentication and CSRF tokens are enabled on the EMS, the EMS will return a random CSRF token with each response that must be used in the next client request. If this token is not included or is incorrect, the request will fail with a 401 Unauthorized error.
Using Services with an EMS
The following services work as REST Web Services with an EMS:
• Restart
• TestPort
The EMS also supports using the isConnected property with a REST Web Service.
|
|
As of v.5.4.2, support for CSRF tokens has been added to the REST API for EMS and LSR. It is enabled by default. Before using the REST API, be sure to read CSRF Token Support in REST API for EMS and LSR.
|