Accessing Domains
This section describes how clients work with domains. The information in this section applies to all the domains installed with Windchill REST Services.
When Windchill REST Services is installed, the servlet WcRestServlet is enabled in the Windchill installation. All requests to the domain resources, which are enabled by Windchill REST Services, pass through this servlet. The root URL to access this servlet is https://<Windchill server>/Windchill/servlet/odata/. When an HTTP GET request is sent to this URL, the servlet responds back with a list of domains available on the server.
From the servlet response, clients can select a domain, and send a GET request to the root URL of the domain to get a list of available entity sets. Clients can send GET, POST, PUT, and DELETE requests to the URLs of the entity sets.
The following URLs are used to interact with Windchill REST Services:
• REST Root URL—https://<Windchill server>/Windchill/servlet/odata/
A GET request to this URL lists the domains available on the Windchill server. Clients can use this URL to get the list of services that are available on a Windchill server.
For example, the request URL is as shown below:
GET https://windchill.ptc.com/Windchill/servlet/odata
• Domain Root URL—https://<Windchill server>/Windchill/servlet/odata/<Domain>
A GET request to this URL returns the information about the entity sets available in the domain. This request is same as that defined in OData protocol for the Service Root URL. The <Domain> in the URL refers to the domain identifier id, which is returned by the REST Root URL in the list of domains.
For example, the request URL to the Domain Root URL of the ProdMgmt domain is as shown below.
GET https://windchill.ptc.com/Windchill/servlet/odata/ProdMgmt/
• Domain Metadata URL—https://<Windchill server>/Windchill/servlet/odata/<Domain>/$metadata
A GET request to this URL returns the entity data model for the domain defined in the Common Schema Definition Language (CSDL). In the OData protocol, this is called the Metadata Document URL.
For example, the output from a GET request to this URL for the PrincipalMgmt domain is as shown below. This URL is used to get information about the entity sets, entities, and entity relations provided by the service. For more information on entity sets, entities, and entity relations, please refer to the OData protocol documentation.
GET https://windchill.ptc.com/Windchill/servlet/odata/PrincipalMgmt/$metadata
Entity Set URL—https://<Windchill server>/Windchill/servlet/odata/<Domain>/<EntitySetURL>
An Entity Set URL references an entity set, which is available in the response of a domain, to a GET request by the Domain Root URL.
For example, if a Domain Root URL contains an entity set called Parts, the Entity Set URL is https://<windchill server>/Windchill/servlet/odata/ProdMgmt/Parts. A GET request to this URL returns a set of entities.
Request URL:
GET https://windchill.ptc.com/Windchill/servlet/odata/ProdMgmt/Parts
Entity Set URL is the main endpoint to perform create, read, update, and delete operations using the HTTP requests POST, GET, PATCH and DELETE respectively.
Let us continue using the above example. To create a part the client sends a POST request to the URL https://<Windchill server>/Windchill/servlet/odata/ProdMgmt/Parts. The body of the request contains a set of property names and values specified in a format that is acceptable to the server. JSON is the preferred format when interacting with Windchill REST service.
To update the part, clients send a PATCH request on the same URL. The body of the PATCH request contains a set of property names and values that will be modified.
To delete a part, clients send a DELETE request to the URL https://<Windchill server>/Windchill/servlet/odata/ProdMgmt/Parts(‘<key>’). In this URL, key is the unique identifier for the part in the entity set. The object reference string in Windchill is treated as the key. To delete a part with object reference ‘OR:wt.part.WTPart:668899’, the DELETE request is https://<windchill server>/Windchill/servlet/odata/ProdMgmt/Parts(‘OR:wt.part.WTPart:668899’).
Clients usually interact with the REST APIs using the Entity Set URL. All the entities in a domain may not have entity sets. Therefore, some entities in the domain are available using navigations. For example, a specific PartUse entity in the ProdMgmt domain is accessed by https://<windchill server>/Windchill/servlet/odata/ProdMgmt/Parts(<part_key>)/Uses(<uses_key>). Here <part_key> and <uses_key> are object reference strings that uniquely identify a part and a usage link.