You will find the following conventions throughout this documentation.
REST endpoint parameters have a type attribute that describes how you supply the parameter to the request. The table below describes the different types you will come across.
| Type | Description |
|---|---|
| path | This type of parameter is supplied directly in the URL, and will be noted in the URL as the name of the parameter surrounded by {} (i.e. /publications/{publicationNodeId}) |
| query | This type of parameter is supplied as a query parameter to the URL. |
| header | This type of parameter is supplied as an HTTP header in the request. |
Most error conditions are reported as HTTP status codes from the service request. The different status codes you can expect from a service and what they mean, are documented on each web service endpoint under the Status Codes section.
There are many common conventions across all of the service endpoints. These are documented below.
Many of the service endpoints require you to specify an item's ID in order to retrieve information. The SCId is the OID of the underlying data object in the format of [FullyQualifiedClassname]-[ID].
com.ptc.sc.ph.SCProductHierarchyRoot-12345
Many of the services that return multiple items support the ability to page the results. All of the services that support paging support the OData paging parameters as described below.
| Param | Description |
|---|---|
| $top | Used to set how many items to include per page. For example, if you had 80 items and wanted to display 10 per page, you would set $top=10. |
| $skip | Used to set how many items to skip before the start of the current page to be displayed. For example, if you had 80 items and set $top=10 and wanted to display page 3, you would set $skip=20. |
To help reduce complexity, the SCList object includes the following named action links to get to the previous page, current page, and next page of results. These links are built dynamically based on the supplied paging parameters. The next and previous links will only be included if the result set warrants it.
| Name | Description |
|---|---|
| action_get_self | The link to get back to the current page of results. |
| action_next_page | The link to get to the next page of results. |
| action_previous_page | The link to get back to the previous page of results. |
The web services are secured using the same technique as your main InService configuration. You will need to supply the username and password, or other authentication header information, in order to successfully execute any web service calls.
There are three important HTTP headers that are needed in order to use the InService REST services, and are described below.
| Header | Description |
|---|---|
| Accept | The Accept header tells the web service what content you will accept in return. Most web services support either JSON or XML based content. Each service endpoint documents what type of content it can return in the media types section of the Response Body documentation. You will need to set your Accept header to one of these values in order for a request to that service to work. |
| Content-Type | The Content-Type header tells the web service what type of content you are sending it. Thusly, this header only applies to web service methods that require you to send data to it. Most of the web services support either JSON or XML content. Each service endpoint documents what content it will accept in the media types section of the Request Body documentation. You will need to set your Content-Type header to one of these values, and supply that type of content to the service, in order for a request to work. |
| Accept-Language | The Accept-Language header tells the web service what language to use in retrieving the data. It could be single language code or a comma separated list of language codes (i.e. en-US, ja). It is recommended that Accept-Language header be set to a valid language code(s), however, this is not a required header for the request to work. |
| x-ptc-active-cart-id | The x-ptc-active-cart-id header tells the web services which cart is the active shopping cart in the client. This cart can then be used to add relevant metadata to a response. It is recommended that x-ptc-active-cart-id header be set to a valid cart, however, this is not a required header for the request to work. |
| x-ptc-dealer-affiliation | The x-ptc-dealer-affiliation header tells the web services what dealer SCId was selected during log in. This dealer then will be used to filter the requested data. It is recommended that x-ptc-dealer-affiliation header be set to a valid dealer SCId, however, this is not a required header for the request to work. |
"actions": {
"action_update_group": {
"method": "POST",
"href": "http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items/update"
},
"action_get_self": {
"method": "GET",
"href": "http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items"
},
"action_create": {
"method": "POST",
"href": "http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items"
},
"action_delete_group": {
"method": "POST",
"href": "http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items/remove"
}
},
,
"method":"PUT", "href":"http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items/com.ptc.sc.cart.SCDefaultCartItem-89967"},
"action_delete_self":{
"domainTypeId":"CartItem","id":"com.ptc.sc.cart.SCDefaultCartItem-89967",
"method":"DELETE",
"href":"http://servername:port/PTC/servlet/servicecenter/rest/carts/com.ptc.sc.cart.SCCart-89966/items/com.ptc.sc.cart.SCDefaultCartItem-89967"}},
"attributes": {
"description": "JUNCTION BOX ASSEMBLY",
"quantity": "1",
"thePersistInfo.createStamp": "2013-06-04T19:41:42.000Z",
"note": null
},
"displayName": "S088557",
"metadata": {
"result": {
"value": "WARN",
"key": "result",
"title": "Part - S079753 has been superseded by Part - S088557. Quantity 1 have been added to cart."
}
},
"domainTypeId": "CartItem",
"wcTypeId": "WCTYPE|com.ptc.sc.cart.SCDefaultCartItem",
"objects": {
"contentRef": {
"actions": {
"action_get_self": {
"domainTypeId": "Part",
"id": "com.ptc.sc.parts.SCPart-86146",
"collectionRefs":{"partslists":{
"method":"GET",
"href":"http://servername:port/PTC/servlet/servicecenter/rest/parts/com.ptc.sc.parts.SCPart-86146/partslists"}}}},
"collections":{},
"objectRefs":{
"topicContext":{
"domainTypeId":"Topic",
"id":"com.ptc.sc.is.SCISNode-87186",
"method":"GET",
"href":"http://servername:port/PTC/servlet/servicecenter/rest/topics/com.ptc.sc.is.SCISNode-87186"},
"productContext":{
"domainTypeId":"Product",
"id":"com.ptc.sc.ph.SCProductHierarchyNode-87314",
"method":"GET",
"href":"http://servername:port/PTC/servlet/servicecenter/rest/products/com.ptc.sc.ph.SCProductHierarchyNode-87314"},
"informationElementContext":{
"domainTypeId":"Element.",
"id":"com.ptc.sc.parts.SCPartsList-86107",
"method":"GET",
"href":"http://servername:port/PTC/servlet/servicecenter/rest/elements/com.ptc.sc.parts.SCPartsList-86107"}},
"id":"com.ptc.sc.cart.SCDefaultCartItem-89967",
"collectionRefs":{}}],
"totalAvailable":1}
Sample JSON and XML are not representative of all service calls, and are only a point of reference to show the structure of the data objects and the possible values returned.
This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:
There is a WADL document available that describes the resources API.
All endpoints act on a common set of data. The data can be represented with difference media (i.e. "MIME") types, depending on the endpoint that consumes and/or produces the data. The data can described by XML Schema, which definitively describes the XML representation of the data, but is also useful for describing the other formats of the data, such as JSON.
This document will describe the data using terms based on XML Schema. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Generally speaking, types define the structure of the data and elements are instances of a type. For example, elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by its type.
http://www.ptc.com/service-center (schema)