ThingWorx Extensibility > Integration Connectors > Integration Connectors Prerequisites > Using ODataConnector or SAPODataConnector > Adding Unavailable Endpoints Using a Swagger Specification
  
Adding Unavailable Endpoints Using a Swagger Specification
For example, consider the following EntityType definitions in an OData specification:
<EntityType Name="Document">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ID" Type="Edm.String"/>
<Property Name="Name" Type="Edm.String"/>
<Property Name="Number" Type="Edm.String"/>
<Property Name="Description" Type="Edm.String"/>
<Property Name="Title" Type="Edm.String"/>
<Property Name="Identity" Type="Edm.String">
.
.
.
<NavigationProperty Name="PrimaryContent" Type="PTC.DocMgmt.ContentItem"/>
</EntityType>
<EntityType Name="ContentItem" HasStream="true">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ID" Type="Edm.String"/>
<Property Name="Comments" Type="Edm.String"/>
<Property Name="Description" Type="Edm.String"/>
.
.
.
</EntityType>
The endpoint that allows adding PrimaryContent to a given Document is not included in the endpoint list that ODataConnector generates from parsing the OData specification. In general, any endpoints that are supported by the backend system for NavigationProperty definitions of an EntityType are not included in the list that the connector generates. Therefore, you should create a Swagger specification that defines these endpoints and add the specification in JSON format as the value of the SwaggerJSON property. For more information, see Using ODataConnector or SAPODataConnector.
For the example above, we know the following from reading the OData specification:
The path for the endpoint will be of the form /Documents('{ID}')/PrimaryContent where
Documents is the name of the entitySet that will contain Document entities in it.
ID is the Key of a Document that is used to uniquely identify a Document instance. The brackets {} around ID indicate that it is a placeholder for a required path parameter, which should be provided when making a request by replacing the placeholder with the actual value.
PrimaryContent is the NavigationProperty of a Document.
PUT is the HTTP operation that supports uploading PrimaryContent for a Document because the PrimaryContent is of type ContentItem. ContentItem has its HasStream property set to True.
A file that should be uploaded as PrimaryContent of a Document is a required input, and the ContentType of the request should be multipart/form-data for successful execution of the request.
The response from executing the endpoint will be one of the following:
A JSON object whose schema successfully conforms to the ContentItem definition.
An error indicating an invalid request.
All requirements for executing a request against the endpoint should be evaluated using an application like the Postman extension for Google Chrome before creating a Swagger specification definition for it.
After evaluating the requirements in Postman, use a tool like Swagger Editor to create a definition for the endpoint.
1. Start the editor with an empty paths object.
2. Add the path for the endpoint and the HTTP operation that the path supports. In the example above, "/Documents('{ID}')/PrimaryContent" and put respectively.
3. Add the input parameter definitions for ID (path parameter) and File (formData parameter).
4. Add the following logic for the endpoint: consumes: [ multipart/form-data ], and produces: [ application/json ].
5. Add responses identified by HTTP status codes that the endpoint will generate.
For example:
Successful operation (HTTP status code 200) will return a JSON object whose schemaconforms to the ContentItem definition. We indicate the reference to the ContentItem definition through the $ref property.
An invalid request (HTTP status code 405).
6. Add a ContentItem definition. Refer to the ContentItem entityType definition in the OData specification to understand the schema.
7. Provide an operationId and summary for the PUT operation.
8. Once all errors reported in the editor have been resolved, and the required paths, operations, and definitions have been added, export the Swagger specification as a JSON file.
9. Copy the contents of the exported JSON file and set it as the value of the SwaggerJSON property.