Invoking extended APIs

Extended APIs are APIs that you provide; they are sometimes called custom APIs. You can use an extended API to invoke an application API or third-party API, as well as to perform custom processing through the Service Definition Framework.

About this task

To invoke an extended API:

Procedure

  1. Code a class.
  2. Code a function that has exactly two parameters of types YFSEnvironment and Document and ensure that the function returns a document.
     public Document <method-name> (YFSEnvironment env, Document doc)
  3. Configure a service that contains an API node. When configuring an API node, use the properties described in the following table.
    Property Description
    General Tab
    Extended API Select this option if a custom API is to be invoked.
    API Name

    Select or enter the API to be called.

    Note: This field is for integration purposes only.
    Class Name Specifies the class you coded in the first step.
    Method Name Specifies the function to be called as coded in the previous step.
    Arguments Tab
    Argument Name

    You can pass name/value pairs to the API by entering the values in the Arguments Tab.

    In order for custom APIs to access custom values, the API should implement the interface com.yantra.interop.japi.YIFCustomApi.

    If entered, these name/value pairs are passed to the custom API as a properties object.

    Argument Value Enter the argument value.
    Template Tab
    XML Template Select this radio button to construct the XML to be used for the API output. Enter the template root element name and click OK. You can then construct the XML.
    File Name Select this radio button to enter the filename of the XML file to be used as the API output template. This file should also exist in your CLASSPATH.

    Facts Tab

    You can configure the Fact Lookup for Database and custom APIs by using the Facts tab. You can define Name-Value pairs for Fact lookup. The Value can be an XML Path.

    Fact Name Enter the fact name.
    Fact Value Enter the fact value.

    When connecting the nodes within a service, keep in mind the API node connection properties as listed in the following API Node Connection Properties table:

    Connection Node Connection Rules
    Can be the first node after the start node Only for services invoked synchronously
    Can be placed before
    • Any transport node except FTP or File IO
    • Any other component node
    Can be placed after
    • Start node
    • Any transport node except FTP or File IO
    • Any other component node
    Passes data unchanged Yes
  4. Make sure the class is in the CLASSPATH of the Service Definition Framework.
  5. Make sure that the class implements a method with a signature that takes in exactly two parameters, a YFSEnvironment and a Document.

    The following example shows how to implement a class:

    import com.yantra.yfs.japi.YFSEnvironment; 
    import org.w3c.dom.Document; 
    public class Bar {
      public Bar () {
        }
      public Document foo(YFSEnvironment env, Document doc)
        {
        //write your implementation code here
        } 
    }
  6. To access the extended API you created, invoke the service containing your extended API.

    For details and sample code that show how to access properties specified when the custom API is configured, see the YIFCustomAPI interface in the application Javadoc.