Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Preparing API Access or a Sandbox Environment

Before you start any connector project, you must first research the target to which you wish to connect. Beyond collecting and reading any API documentation offered by the target’s provider, you must also prepare access to an instance of the target so you can test against it. 

Sandbox access, supporting code and documentation, and other support required for building a connector to a local enterprise application or other Web service is usually provided by your local administrator or the application vendor. SaaS applications usually provide a self-service process for accessing the API, which varies from service to service.

This document summarizes typical preparation steps you might need to perform, then presents examples for two cases: Salesforce Example and Twitter Example.

Assumptions

This document assumes you are familiar with your target application, Web service or other resource, and that the documentation for your target’s APIs or client library is publicly available.

API Access and Java Libraries for Cloud Services

For cloud services, you generally obtain access to the API according to the following steps.

  1. Set up a test account, sandbox environment, and API access privileges with the application provider. Generally, there are several separate steps required to complete these tasks. 

  2. Download any required supporting Java libraries for accessing the service. These may be client libraries that are the only means of accessing the application, or they may be a wrapper for the application’s publicly exposed Web service. Often, it is easier to build a connector based on these libraries than to call the API directly in the connector code.

  3. For SOAP-based connectors such as the Salesforce connector, you need to obtain a  WSDL file from the API provider. You may also need to generate a supporting Java library (as a JAR file) from the WSDL, as described in the Salesforce Example below. DevKit can use this JAR to obtain metadata about the API, its exposed operations, and its supporting Java classes.

  4. If the API requires the use of a client library or other Java libraries, you must include them as Maven dependencies in your project. For details, see the section on Including External Libraries as Maven Dependencies in the Salesforce example below.

The examples below are accurate at the time of writing this guide; however, bear in mind that the API owners may change their instructions over time.

Salesforce Example

Prepping to build a Salesforce connector, you need to complete three tasks:

  1. set up a Salesforce developer account

  2. acquire two Salesforce JAR files

  3. include external libraries as Maven dependencies

Setting Up a Salesforce Developer Account

  1. Register for a Salesforce account. You need to provide an email address to receive a confirmation email.

  2. After you’ve filled out the registration form, open the confirmation email and click the link provided to enable you to set a password and log in to Salesforce Developer Edition.

  3. To enable remote applications to log in to Salesforce, you must reset your security token on Salesforce by completing the following steps:

    1. From the Salesforce UI, select Your Name > Setup in the upper right corner.

    2. Expand the My Personal Information on the left sidebar, then select Reset Security Token.

    3. On the Reset Security Token page, click the Reset Security Token button. Salesforce emails a new Security Token.

  4. Record your security tokenusername and password as these items are required to complete the example below. 

Creating Salesforce JAR Files

You must acquire two Salesforce JAR files needed to build the connector.

  • The first is the Salesforce Web Service Connector, which is a Web services client stack for accessing Salesforce APIs. 

  • The second is the Partner JAR, which contains the framework for accessing Salesforce data in a metadata-driven, dynamically-typed way. This framework is distributed as a WSDL file, so you can generate a JAR file for it.

    1. Download the Salesforce Web Service Connector JAR file.

    2. If you have not already done so, log in to Salesforce.com.

    3. In the upper right corner, select  Your Name  >  Setup.

    4. In the left sidebar, expand the Develop heading, then select API.

    5. Click Generate Partner WSDL, then save the content as a file to your local drive.

    6. Once you’ve saved the WSDL to your computer, use the following command to compile it into a JAR to generate the file to your working directory (the directory at which your terminal session is located). Run the command below (xx represents the version of the WSC JAR file).

      java -classpath <pathToJar>/wsc-xx.jar com.sforce.ws.tools.wsdlc pathToWSDL/wsdlFilename wsdlGenFiles.jar

      For example, if your WSC JAR file is at /Users/doug/workspace/connector, and your WSC JAR file is wsc-23.jar, run the following:

      java -classpath /Users/doug/workspace/connector/wsc-23.jar com.sforce.ws.tools.wsdlc pathToWSDL/wsdlFilename wsdlGenFiles.jar

Find your Current Directory

Unix or Unix-based (Mac OS X, Linux):

When you open a terminal, you usually start in your home directory ( /home/<user> in Linux, /User/<user>). The terminal prompt usually displays the complete path to your working directory; if it is not, you can see it by running the pwd command.

Windows:

When you open a terminal, you usually start in your home directory. The terminal prompt usually displays the complete path to your working directory; for example C:\Documents and Settings\All Users\doug.

For further details about obtaining and compiling the JAR file, consult the instructions from Salesforce.

Including External Libraries as Maven Dependencies

You must add any JARs specific to your target system or application to your DevKit Maven project as Maven dependencies. In this example, you must add the two Salesforce JARs to the Maven project in Eclipse.

For details on building applications with Maven, see Introduction to the Maven Build Cycle in the official Maven documentation.
  1. Maven maintains a local repository on your development machine, and since the JAR files are also hosted on your machine, you must first add them to this local repository so Maven can find them at build time. Maven provides a goal add the JARs to the local repository. From the command line, run the following command:

    mvn install:install-file -Dfile=<PATH_TO_FILE> -DgroupId=salesforce -DartifactId=partner -Dversion=1 -Dpackaging=jar
  2. Then, run the following command, where  <`PATH_TO_FILE`> is the path to the respective JAR file and <VERSION> is the version of salesforce partner WSDL you downloaded.

    mvn install:install-file -Dfile=<PATH_TO_FILE> -DgroupId=salesforce
        -DartifactId=wsc -Dversion=<VERSION> -Dpackaging=jar
  3. Create a new Maven project in Eclipse. (You can use IntelliJ or Mule Studio as your IDE; this procedure uses Eclipse.)

  4. Add these two JAR files as Maven dependencies. In Eclipse’s Package Explorer, right-click the project name, then select Maven > Add Dependency

  5. In the Add Dependency wizard, enter the Group IdArtifact Id, and Version for the Salesforce Partner JAR (see below, left). Since these JARs are stored in the local repository, the Group Id, Artifact Id, and Version can be arbitrary values, as long as they match between the installed name and the Maven dependency. Click OK

  6. Repeat steps 5 - 6 to add the WSC JAR to your project as a dependency (see below, right).

Twitter Example

Twitter is a good example of a relatively simple API to access from a connector as many Web applications or services follow a similar model.

  1. To access the Twitter API, you must first obtain a Twitter account

  2. To access Twitter APIs through the account you created, you need to create an empty Twitter application at Twitter’s developer portal.

  3. To test the Twitter connector, obtain the following elements from Twitter:

    • Access key

    • Access secret

    • Consumer key

    • Consumer secret

  4. For detailed instructions on creating an application on the Twitter platform, see Configure Twitter for API Access.