Introduction: Creating flows for an API (Part 1)

A flow for an API contains a request, one or more target application actions, and a response for an API operation. The flow is triggered by calling the API operation such as from mobile and web applications.

If you want a developer to be able to create an app that makes use of the data in your applications, you can provide an API. For example, you might provide an API that can create, retrieve, and update customers in your CRM system. Defining the API involves the following steps:

  1. You create one or more models that define the structure of the objects that you want to create or retrieve.
  2. You choose the create, retrieve, or update operations to perform against each model.
  3. You configure a flow that implements each operation, adding one or more target applications that hold the data.

Watch the video:

The following steps describe how to create a flow for an API in App Connect to create a Salesforce contact.

First, find or create everything you need:

  • (If you haven't already connected App Connect to your Salesforce account) The name and password of your Salesforce account.
    Note: If you want to create a free test account in Salesforce rather than use your business account, make sure that you register for a Developer account from this URL: rather than a Trial account. If you connect to App Connect with a Trial account, the Salesforce events do not work.

Next, create the flow for the API:

  1. On the Dashboard, click New > Flows for an API.
  2. At the top of the page, enter a name that identifies the purpose of your API, for example: Customer API
    Figure 1. Enter a name that identifies your API
    Enter a name that identifies your API

    (Click the image to view full size.)

  3. In the Model name field, you need to enter a name for your model that reflects the type of object that your API will work with.

    The API flow that we are going to create will create a customer in Salesforce. So, in the Model name field, type Customer

  4. Click Create model. The Customer model panel is displayed.

    This panel contains 2 tabs; a Properties tab and an Operations tab.

    First we're going to work with the Properties tab. Properties are required to define the structure of the object that the API will work with.

    1. Our API will create, update, and retrieve a customer so we're going to use the following properties to identify customers.
      • CustomerID
      • FirstName
      • LastName
      • Email

      Add these properties to the Customer model. (To add the first property, type the name in the field provided. To add another property to the list, click Add property (+)).

      Figure 2. Adding properties for the API.
      Adding properties for the API.

      (Click the image to view full size.)

      A valid property name has the following characteristics:
      • Each property name must be unique.
      • A property name can't contain spaces, but you can use an underscore character (_) to separate words.
      • It must contain only letters, numbers, or the underscore character.
      • It must contain at least 2 characters.
      • It must begin with a letter or an underscore.
      Tip: You can either type in the name of a property, or click Select properties from applications to choose properties from one or more of the applications that you're connected to.
    2. By default, the first property that you add (CustomerID) has the ID option selected. Because we want our flow to return a customer ID when we create the customer object, we'll leave this default.
      Note: A property that is set as the ID indicates that your flow must return this property when creating an object or that the property must be sent in a request to update or retrieve an object by using its ID. You can only use ID against one property.

      You can create more models by clicking Create model. To delete a model, select Delete model from the menu.

  5. To define how the API will interact with the object, click Operations. You can add operations to:
    • Create an object.
    • Retrieve an object by using its unique ID or by using a filter.
    • Update or create an object (by using its ID or a filter), where the object is updated if it exists, or created if it doesn't.
    1. Add the Create Customer operation to the Customer model. (Click within the Select an operation to add drop-down list, and then select Create Customer.)
      Figure 3. Adding the Create Customer operation
      Selecting the Create Customer operation
      Note: You can define your own operations, by clicking Add a custom operation. Note the following restrictions if you decide to use this option:
      • The operation name can't be a keyword.
      • The operation name can't be one of the following keywords: create, updateOrCreate, all, updateAttributes, update, updateAll, upsertWithWhere, replaceOrCreate, replaceById, destroy, destroyAll, executeAssembly.
      • The query parameter can't be the same as the model ID.

      For more information about adding custom operations see, Create your own custom HTTP operations on API flows.

      Next, we're going to create a flow that defines how the Create Customer operation will work.

  6. Click Implement flow. You'll see a basic flow in the flow editor, with a Request node, a Response node, and a (+) space to add one or more target applications. Notice the the structure of the Request body example, it is constructed from the properties in your model, with some sample data.
    Figure 4. Request body example from the Customer model, with some sample data
    Request body example from the Customer model, with some sample data
  7. To add the target application to the flow, click (+).
  8. Select Salesforce > Contacts > Create contact.

    (If you haven't already connected App Connect to Salesforce, specify the name and password of your Salesforce account.)

  9. Map the fields from the request into the Salesforce 'Create contact' action as follows:
    • Account ID: Click within the field and click Insert a mapping Insert a mapping icon. Then select CustomerID from the Available inputs list.
    • Last Name: Type last and then select LastName from the list.
    • First Name: Type fir and then select FirstName from the list.
    • Email: Type em and then select Email from the list.
    Figure 5. Map fields from the request into 'Salesforce / Create contact'
    Mapped fields for the Salesforce action
  10. You can also add some conditional logic to your flow. For example, if you want your flow to do different things for different conditions, you can add one or more ‘If’ nodes to your flow. For more information, see Adding conditional logic to a flow.
  11. Click the Response node in the flow to define the response that'll be returned when the operation has completed successfully. Map the available fields from 'Salesforce / Create contact' to the response as follows:
    • For the required response field CustomerID, map the Salesforce field Contact ID; optionally, map other fields to return their values in the response.
      Figure 6. Map the available fields from 'Salesforce / Create contact' to the response
      API response node mappings
      Note: In the Response header section, you can choose your own response code mapping. The following response codes are returned for the different operations:
      • Create operations return a response code of 201 (record created).
      • Retrieve operations return a response code of 200 (record retrieved).
      • Replace or create operations return a response code of 200 (record replaced) or 201 (record created).
  12. Click Done to return to your model.
  13. From the options menu (⋮), click Start API.
    Figure 7. Start API in the options menu
    Start API in the options menu

Finally, test the flow for your API:

If you are using App Connect on IBM Cloud®, you can test the flow for your API in the API portal. Otherwise, you can test the flow for your API in your preferred method for invoking an API, such as by using Postman or curl.

Testing in the API portal

  1. Click the Manage tab and then scroll down to the Sharing Outside of Cloud Foundry organization section (at the bottom of the page).
  2. Click Create API key and documentation link. Notice that a generated API key is automatically provided in the "Create API key" field. You can use this key or specify your own custom key.
  3. Give the key a descriptive name; for example: Customer API test, and then click Create.

    API key for testing flow for API in API portal. (Click the image to view full size.)

  4. Copy the API Documentation Link link and paste into your web browser to open the API in an API portal.
  5. Click the API operation, for example Post / contacts, to show the Details tab for the API operation.
  6. To invoke your API in the API portal, click the Try it tab.
  7. In the Security / Client ID field, paste the API key.
  8. Scroll down to the "Parameters" section, and then click Generate to generate some sample customer data in the data field. You should see sample data similar to this:
    "CustomerID": "2766950149128192",
    "FirstName": "Test1",
    "LastName": "APIname",
    "Email": ""
  9. Delete the CustomerID line from the generated data because an ID doesn't need to be provided when creating a contact in Salesforce. (The CustomerID line was included in the generated data because we defined it as one of the properties for the Customer model. This value is generated and returned by Salesforce when a contact is created.)
  10. Click Send.
  11. Scroll down to the "Response" section, where you should see the success code: 201 Created and the response body containing the CustomerID value assigned by Salesforce.
    Code: 201 Created
      "CustomerID": "0034I00001pvaenQAA"
  12. You've created abd tested your API! Close the API portal tab to return to the API flow. Then, click Dashboard to return to the App Connect Dashboard.

    In the Dashboard, you should be able to see the Customer API tile for your API flow. You can start and stop your API flow in the same way as any other flow. You can also open the API flow while it's running, but you'll have to stop it before you can edit it.

  13. Go to your Salesforce instance, and open Contacts. You'll notice that a new contact for your sample data has been created.
    Salesforce contact created by an API flow

    If you want to find out how to retrieve and update Salesforce contacts using the same API, see Creating flows for an API (Part 2).

Testing in Postman

In this example, we test a flow for an API that was created and started in App Connect purchased from IBM Marketplace.

    1. To test your API, in this tutorial, we're going to use Postman; however, you can use your preferred utility, for example, the Linux® command line and curl, or the HttpRequester add-on for Firefox.
    2. Open the Postman utility. (The following steps use Postman version 5.3.1. Some steps might differ slightly for different versions.)
    3. First we're going to test the Create Customer operation by selecting the POST function in Postman.
    4. From the API Portal window, copy the API base URL and paste it into the Enter request URL field in Postman.

    5. In the Authorization tab, change the Type to OAuth 1.0.
    6. Go to the Headers tab then copy the following key/value pairs from the API portal window:
      • Key: X-IBM-Client-id
      • Value: this is the value code from the API portal
      • Key: Content Type
      • Value: application/json

    7. Go to the Body tab, select raw and add the following text to the palette: { "FirstName": "Test1", "LastName": "APIname", "Email_Address": "" } Info: Note that the request body doesn't include the API ID property (CustomerID) because that's set by Salesforce.
    8. Click Send.
    9. The response is posted in the Response palette as displayed in the following image. When you're creating an object, typically only the ID from the target application will be returned in the response message. (Click the image to view full size.)
    10. Open Salesforce, go to contacts and you'll notice that a new contact has been created.

    11. To manage your API, go back to the API flow in the App Connect UI and click the Manage tab.
    12. Then click API definition to download your API document. Note that the file can be exported as a YAML or JSON file or it can be opened in API Connect.
    13. Click Show all to view your API
    14. After you have downloaded the API, you can import it into your API management tool. We've provided the URL, user name, and password that your API management tool will need.


You've created and tested your API!

In flow tiles on the App Connect Dashboard, flows for APIs are identified by the API icon. You can start and stop them in the same way as any other flow. You can open an API while it's running, but you have to stop it before you can edit it.

Figure 8. The flow tile on the App Connect Dashboard

If you want to find out how to retrieve and update Salesforce contacts using the same API, see Creating flows for an API (Part 2).