Adding Unavailable Endpoints Using a Swagger Specification

ThingWorx Model Definition in Composer > Modeling > Integration Connectors > Integration Connectors Prerequisites > Using ODataConnector or SAPODataConnector > Adding Unavailable Endpoints Using a Swagger Specification

For example, consider the following EntityType definitions in an OData specification:

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 then 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, such as the Postman extension for Google Chrome before creating a Swagger specification definition for it.

After evaluating the requirements in Postman, use a tool such as 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 schema conforms 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. After you resolved the reported errors in the editor, 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.