Extracting IDL using the REST API

This document covers the following topics:

Introduction

You can call the IDL Extractor for Integration Server from a command line, using the REST API. A simple service performs the extraction only; an advanced service also creates a listener connection and listener services. The returned IDL file representation is part of the JSON response in standard Base64 encoding, so you can easily save the content to disk after decoding. Base64 encoding/decoding is used to keep the source file formatting inside the JSON format. See Base64 Resources for information on Base64 encoding/decoding tools.

Start of instruction setTo extract IDL

  • Send the request to the Integration Server to the following URL:

    http://integrationServerHostName:5555/restv2/wmentirex/extractIdl

    Example:

    http://localhost:5555/restv2/wmentirex/extractIdl

Start of instruction setTo extract IDL and create listener connection service

  • Send the request to the Integration Server to the following URL:

    http://integrationServerHostName:5555/restv2/wmentirex/extractIdlAndCreateListenerConnection

    Example:

    http://localhost:5555/restv2/wmentirex/extractIdlAndCreateListenerConnection

Extracting IDL

Configuring your Input Parameters

Start of instruction setTo configure your input parameters

  • Use a JSON request document. The following parameters are available:

    Parameter Opt/
    Req     		Description
    sourcePackageName R The package name from you want to extract.  
    services O An array of full names of Integration Server services available in the source package, for example pub.string:toLower.
    stringType O The IDL data type that is used for string data types. Possible values:
    AV (default), AVn, An.
    language R The target language for the RPC clients. Possible values:
    COBOL, Natural, PL/I, Other.

    Sample request document example.json: 

    {
     "sourcePackageName": "EntireXDemo",
     "services": [
          "folder1.folder2:service1",
          "folder1.folder2:service2"
     ],
     "language": "Natural"
}

Calling the REST Service

Start of instruction setTo call the REST service

  • Provide the host name, port and credentials for the Integration Server.

    This example uses the executable curl: 

    curl -u <username>:<password> -X POST -H "Content-Type: application/json"
 -d @.\example.json http://<integrationServerHostName>:5555/restv2/wmentirex/extractIdl

Response Codes

The HTTP response is in JSON format.

  • Successful Request
    If a request is successful, the following parameters are returned and error is empty. Example: 

    {
     "idlSourceBase64":"LyogR2VuZXJhdGVkIGJ5IFNvZnR3YXJlIEFHLCBJREwgRW50aXJlWCAuLi4=",
     "mapToString":"false",
     "error":null
}
    where idlSourceBase64 is the Base64-encoded source, and
      mapToString indicates whether all data items were mapped to String. Valid values: true, false.

    The HTTP response code is 200 (OK).

  • Unsuccessful Request
    If a request is not successful, the error parameter contains the reason for the failure. Example: 

    {
  "idlSourceBase64": null,
  "error": "Required parameter language is missing"
}

    The HTTP response code is 500 (internal server error).

  • Invalid Syntax
    If the JSON input file has a syntax error (invalid input), the error parameter contains the reason for the JSON parser failure: 

    {
  "idlSourceBase64": null,
  "error": {
  "$errorDump": "com.fasterxml.jackson.core.JsonParseException:Unexpected character
  (';' (code 59)): was expecting comma to separate Object entries\n at [Source:
  (com.wm.net.HttpInputStream); line: 1, column: 36]",
...
}

    The HTTP response code is 400 (bad request).

Extracting IDL and Creating a Listener Connection Service

Configuring your Input Parameters

Start of instruction setTo configure your input parameters

  • Use a JSON request document. The following parameters are available:

    Parameter Opt/Req Description Note
    sourcePackageName R The package name from which you want to extract.  
    services O An array of full names of Integration Server services available in the source package, for example pub.string:toLower.  
    stringType O The IDL data type that is used for string data types. Possible values:
    AV (default), AVn, An.     		 
    language R The target language for the RPC clients. Possible values:
    COBOL, Natural, PL/I, Other.     		 
    targetPackageName R The package name to store the connection and listener services.  
    connectionType R The type of the listener connection. Possible values:
    RpcListenerConnection, DirectRpcListenerConnection, ReliableRpcListenerConnection, DirectReliableRpcListenerConnection.     		Reliable RPC does not allow output parameters inside the extracted IDL.
    folderName R The name of the folder inside the target package.  
    connectionName R The name of the listener connection.  
    listenerName R The name of the listener service.  
    serverAddress R The address of the RPC server. The address is given in the format <class>/<server>/<service>.  
    brokerID R The Broker ID. Not applicable to Direct RPC Listener Connections.
    userid O The user ID for secured communication.  
    password O The password for secured communication.  
    encoding R The data encoding.  

    Sample request document example.json: 

    {
     "sourcePackageName": "EntireXDemo",
     "services": [
          "folder1.folder2:service1",
          "folder1.folder2:service2"
     ],
     "language": "Natural",
     "targetPackageName": "CustomerPackage",
     "connectionType": "DirectRpcListenerConnection",
     "folderName": "folder3.folder4",
     "connectionName": "connection1",
     "serverAddress": "RPC/JSON1/CALLNAT",
     "listenerName": "listener1",
     "encoding": "UTF-8"
}

Calling the REST Service

Start of instruction setTo call the REST service

  • Provide the host name, port and credentials for the Integration Server.

    This example uses the executable curl: 

    curl -u <username>:<password> -X POST -H "Content-Type: application/json" 
-d @.\example.json http://<integrationServerHostName>:5555/restv2/wmentirex/extractIdl

Response Codes

The HTTP response is in JSON format.

  • Successful Request
    If a request is successful, the following parameters are returned and error is empty. Example: 

    {
     "idlSourceBase64":"LyogR2VuZXJhdGVkIGJ5IFNvZnR3YXJlIEFHLCBJREwgRW50aXJlWCAuLi4=",
     "mapToString":"false",
     "infos":[
          "Connection folder3.folder4:connection1 created"
     ],
     "error":null 
}
    where idlSourceBase64 is the Base64-encoded source,
      mapToString indicates whether all data items were mapped to String (valid values: true, false), and
      infos is an array of status information, for example Connection abc:def created.

    The HTTP response code is 200 (OK).

  • Unsuccessful Request
    If a request is not successful, the error parameter contains the reason for the failure. Example: 

    {
  "idlSourceBase64": null,
  "info": null,
  "error": "Required parameter connectionName is missing"
}

    The HTTP response code is 500 (internal server error).

  • Invalid Syntax
    If the JSON input file has a syntax error (invalid input), the error parameter contains the reason for the JSON parser failure: 

    {
  "idlSourceBase64": null,
  "error": {
  "$errorDump": "com.fasterxml.jackson.core.JsonParseException:Unexpected character
  (';' (code 59)): was expecting comma to separate Object entries\n at [Source:
  (com.wm.net.HttpInputStream); line: 1, column: 36]",
...
}

    The HTTP response code is 400 (bad request).