Build a Web API to expose Salesforce.com objects

Easy assembly with IBM WebSphere Cast Iron Web API Services

In this article, API developers can learn how to use IBM® WebSphere® Cast Iron® Web API Services to create a web API that can be invoked to create a contact in the Salesforce.com customer relationship management system. With IBM WebSphere Cast Iron Web API Services, you can assemble and expose APIs with just a few clicks. You can also analyze your web API usage via the analytics provided as well as socialize your web API communities in a branded developer portal with community hooks.

Katherine Sanders (katherine_sanders@uk.ibm.com), IBM Software Services for WebSphere, IBM

Author photo - Katherine SandersKatherine Sanders is an IT specialist based at IBM Hursley, United Kingdom. She has worked at IBM since 2007 and is currently focusing on IBM WebSphere Cast Iron cloud integration. She has a strong background in software development and the WebSphere product portfolio. Katherine holds a Bachelor of Science degree in computer science from the University of Nottingham.


developerWorks Contributing author
        level

02 July 2013

Also available in Chinese Japanese Vietnamese

Introduction

Try Cast Iron Live Web API Services

Sign up for a free, 90-day cloud-hosted trial of Cast Iron Live Web API Services.

Web APIs are a fast-growing business channel that helps your enterprise reach new markets and engage new customers and partners. They also help you tap into innovation from a large community of developers, not just the developers in your company.

Because Web APIs expose key business assets and services such as product catalogs or phone listings, they act as an external persona for your enterprise. They should be self-describing and simple to use. They should also use the Representational State Transfer (REST) architectural style so they can be easily invoked from a browser or mobile device.

With IBM WebSphere Cast Iron Web API Services, you can assemble and expose APIs with just a few clicks. You can also analyze your web API usage via the analytics provided and socialize your web API communities in a branded developer portal with community hooks. This article guides you step-by-step in using the WebSphere Cast Iron Web API to create a web API that can be invoked to create a contact in the Salesforce.com customer relationship management (CRM) system.

Prerequisites

This article is primarily aimed at API developers. It contains detailed steps for creating an example web API, so even beginners should be able to complete it. However, prior knowledge of JavaScript Object Notation (JSON) and REST will increase your understanding of the material.

To implement the example in this article, you need:

  • A workstation with a standard Internet browser (Google Chrome 18 or later, Mozilla Firefox 10 or later, or Internet Explorer® 9 or later)
  • An Internet connection
  • A valid Cast Iron Web API administrative ID and login credentials (you can sign up for a free trial)
  • A valid Salesforce.com account and login credentials (you can sign up for a developer account).

Creating and testing the web API

Imagine an enterprise that uses Salesforce.com to store its CRM information, but only the company's employees have access to it. The enterprise wants to expose a web API to allow application developers to create innovative mobile applications that can access the Salesforce.com environment. For example, they could create an application that would allow customers to add their contact details directly into Salesforce.com if they wanted to be contacted by a sales representative. To enable this functionality, follow the step-by-step instructions provided in this article to create and test a Salesforce.com web API that exposes a resource called create_contact.

  1. Launch Cast Iron Web API Services by opening https://webapi.castiron.com in a browser.
  2. Click Sign In at the top right, enter your credentials in the window, then click Sign In, as shown in Figure 1.
    Figure 1. Sign in to Cast Iron Web API Services
    Image showing how to sign into Cast Iron Web API Services
  3. On the Getting Started with Web API page, click Create or the APIs menu item at the top to create a new API, as shown in Figure 2.
    Figure 2. Create a new API
    Image showing how to create a new API
  4. In the Create new API box, enter the API name as Salesforce.com, the context as salesforce, and the description as API to expose Salesforce.com objects, as shown in Figure 3 and Figure 4.


    Note that the Uniform Resource Indicator (URI) for the API is displayed at the bottom of the Create new API box. The URI is in the format:

    https://<company>.web.castiron.com/<context>,

    where <company> is your web API company name, and <context> is the context you just entered.

    Click Create.

    Figure 3. Enter the API name and description
    Image showing how to enter the API name and description
    Figure 4. Enter the API context
    Image showing how to enter the API context

    After the API has been created, it appears below the Create new API box.

  5. Click the API name to edit it and add a resource to the API, as shown in Figure 5.
    Figure 5. Edit the API by clicking its name
    Image showing how to edit the API by clicking its name

    Alternatively, click the Pencil icon on the right side of the window, as shown in Figure 6.

    Figure 6. Or edit the API by clicking the Pencil icon
    Image showing how to edit the API by clicking the Pencil icon
  6. In the Add a Resource box, select the HTTP action POST, enter the URI as create_contact, and enter the description as Create a Salesforce.com contact, as shown in Figure 7.
    Figure 7. Enter the resource details
    Image showing how to enter the resource details

    Note that the URI for the resource is displayed at the bottom of the Add a Resource box. The URI is in the format <API URI>/<resource URI>, where <API URI> is the URI for the API you created above and <resource URI> is the URI you just entered. Click Add.

    After the resource has been created, it appears below the Add a Resource box.

  7. Click the resource name to edit it and implement the resource.
  8. On the Resource Details tab that appears, you can configure the parameters, request headers, request body format, response headers, and response body format for the resource. Enter the JSON code in Listing 1 in the Request Body text area to define the structure of the request body you should use to invoke this resource.

    In this example, only the contact name, address, and email address are available for you to set through the API, but you could include all the fields in the Salesforce.com contact object here. Note that the resource will automatically be saved as soon as you click outside the text area.

    Listing 1. Example request body in JSON format
    {
        "FirstName": "Katherine",
        "LastName": "Sanders",
        "Street": "IBM Hursley",
        "City": "Winchester",
        "County": "Hampshire",
        "Postcode": "SO21 2JN",
        "Country": "UK",
        "Email": "katherine_sanders@uk.ibm.com"
    }
  9. Enter the JSON code in Listing 2 in the Response Body text area to define the structure of the response body that this resource will return when it has been invoked.

    If Salesforce.com contact creation is successful, the API returns the object ID, and the success value will be true. However, if an error occurs, the success value will be false, and the error fields will be set instead of the ID.

    Listing 2. Example response body in JSON format
    {
        "id": "003A0000016nDhJIAU",
        "success": "true",
        "error_field": "",
        "error_message": "",
        "error_code": ""
    }
  10. Click the Implement Resource tab, shown in Figure 8.

    On this tab, you define the resource implementation using a configuration approach. You can access databases, Salesforce.com, and other APIs or services available over HTTP.

    Figure 8. Implement the resource
    Image showing how to implement the resource
  11. Click the plus sign (+) under Request on the left side of the window to add a data source, as shown in Figure 9.
    Figure 9. Add a data source
    Image showing how to add a data source
  12. Select Create objects under Salesforce.com in the menu that appears to create a new request activity.

    You can create one or more request activities per request.

  13. Click the request activity to configure it, as shown in Figure 10.
    Figure 10. Configure the request activity
    Image showing how to configure the request activity
  14. Enter a name for the connection and your Salesforce.com credentials, and then click Connect, as shown in Figure 11.

    A status message appears at the bottom of the window to let you know whether the connection was successful. Your credentials will also now be available in the Existing Connections list at the top, so you won't need to re-enter them in future.

    Figure 11. Connect to Salesforce.com
    Image showing how to connect to Salesforce.com

    The Discover step of the configuration should load automatically after successfully connecting to Salesforce.com. Cast Iron Web API loads the list of available objects from your Salesforce.com environment.

  15. Select the Contact object, and wait for the list of available fields to load on the right side of the page, as shown in Figure 12.
    Figure 12. Select the contact object
    Image showing how to select the contact object
  16. Click the Clear All link to clear all the check boxes, and then select the fields you will set with values from the request body, as shown in Figure 13.

    In this example, the required fields are FirstName, LastName (selected by default, because it's mandatory), MailingStreet, MailingCity, MailingState, MailingPostalCode, MailingCountry, and Email. When you're finished, click the Configure step at the top of the page.

    Figure 13. Select the fields to set in the created object
    Image showing how to select the fields to set in the created object
  17. You can use either of two methods to map the data from the request body to the Salesforce.com fields in the new contact object. The Select Values method loads first and allows you to click the Select Available Value link next to each Salesforce.com field and a value from the request body to use, as shown in Figure 14.

    Click MAP VALUES at the top right to access the second method.

    Figure 14. Select values for each field
    Image showing how to select values for each field
  18. The Map Values method allows you to graphically map fields from the request body to Salesforce.com fields. Drag the circle next to each request field to the corresponding Salesforce.com field from Table 1, as shown in Figure 15.

    Optionally, you can apply a function to each mapping by clicking the plus sign on the line between the fields. A full list of the available functions is available in the Cast Iron Express product documentation (see Resources for a link).

    Figure 15. Map values for each field
    Image showing how to map values for each field
Table 1. Request mappings
Request body fieldSalesforce.com contact field
FirstNameFirstName
LastNameLastName
StreetMailingStreet
CityMailingCity
CountyMailingState
PostcodeMailingPostalCode
CountryMailingCountry
EmailEmail
  1. Click Select Values at the top right to return to the first method, if you would like to view a textual version of the mappings, as shown in Figure 16.

    The Salesforce.com fields are listed on the left, and the fields from the request body are listed on the right.

    Figure 16. Display a textual version of the mappings
    Image showing how to display a textual version of the mappings
  2. Click Response on the left side of the page, then click MAP VALUES on the right. Complete the mappings in Table 2 from the Salesforce.com response fields to the fields in the response body for the resource, as shown in Figure 17.

    Note that the mapping for the success field is amber, because a mismatch exists in datatypes. You can ignore this warning, because the Boolean success field from Salesforce.com can be automatically converted into a string success field for the response body. For more information about defining mappings, see Resources.

    Figure 17. Response body mapping
    Image showing response body mapping
Table 2. Response mappings
Salesforce.com response fieldResponse body field
results/result/errors/fieldserror_field
results/result/errors/messageerror_message
results/result/errors/statusCodeerror_code
results/result/idid
results/result/successsuccess

You have finished implementing a resource that can create a Salesforce.com contact using the information passed in the request body. The resource returns a response body with either the contact ID or error details, if the creation was unsuccessful. However, before you can test the resource, you must create an entitlement.

For each web API, you can define up to three API entitlement levels. These entitlements reflect different levels of usage, security, and pricing. Click the Salesforce.com link at the top of the page to return to the API configuration, then click the Entitlements tab. In the Add an Entitlement box:

  1. Enter the name as Basic.
  2. Enter the description as Basic entitlement.
  3. Enter the security level as Requires Id.
  4. Enter calls per minute as 10.

Finally, click Add (see Figure 18).

Figure 18. Enter the entitlement name, description, and calls per minute
Image showing how to enter the entitlement name, description, and calls per minute

After the entitlement has been created, it appears below the Add an Entitlement box. You must also activate the resource before you can test it. Click the Resource Definition tab at the top of the page, and then click the Play icon next to the create_contacts resource to start it.

An information window appears, stating that the resource was activated successfully. Click OK. Now, you are ready to test the resource.


Testing

To test the resource you've created, complete the following steps:

  1. Click the Test tab, and then select the create_contact resource from the Resource list, as shown in Figure 19.

    Doing so loads the example request body from Listing 1 that you used in the resource configuration.

    Figure 19. Select the resource to test
    Image showing how to select the resource to test
  2. Select Test application from the Application list, and then click Test, as shown in Figure 20.

    This application is provided to allow you to test your resources without having to create an application first.

    Figure 20. Select the test application
    Image showing how to select the test application
  3. Wait for the response to appear in the bottom half of the screen, as shown in Figure 21.

    You know that the request was successful because the error fields are empty, the success field is "true", and the ID field contains the ID of the contact created in Salesforce.com.

    Figure 21. A successful response
    Image showing a successful response

    Now, test an error case to ensure that error fields in the response are populated correctly.

  4. Change the LastName in the request body to "", and then click Test.

    As expected, an error is returned in the response body, because the LastName field is mandatory in Salesforce.com; the ID is empty, because the create failed, as shown in Figure 22.

    Figure 22. Error response body
    Image showing the error response body

Conclusion

This article demonstrated how to create a Salesforce.com web API using Cast Iron Web API. It showed how to expose a resource called create_contact in the API and how to test the resource by making two HTTP POST requests to it. The first request successfully created a Salesforce.com contact and returned the ID. The second request failed and returned the error details instead of the ID as expected.

When an API is ready to release to the developer community, you should make it public by clicking Public at the top right of the API configuration page. Doing so makes the API visible in the developer portal. You can access your developer portal by following the steps in the Web API documentation.

You should also customize the developer portal to match your company branding. These pages are important, because they are seen by external users, they publicize your company, and they are key in creating new business opportunities. To access this configuration, click your user name at the top right of the page, and then select the Customize Developer Pages option in the menu that appears. See the Web API documentation for further information.

After developers have started using your web APIs, you can also monitor the application developers and entitlement requests as well as analyze API traffic.

Resources

Learn

Get products and technologies

Discuss

  • Follow Cast Iron Web API on Twitter at @ibmapimgt.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Mobile development on developerWorks


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Mobile weekly

    Innovations in tools and technologies for mobile development.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, Cloud computing, WebSphere
ArticleID=936414
ArticleTitle=Build a Web API to expose Salesforce.com objects
publish-date=07022013