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 uses 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. To define the API, you complete the following high-level 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 complete against each model.
  3. You configure a flow that implements each operation, adding one or more target applications that hold the data.

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

Find or create everything you need

  • If you're not already connected to your Salesforce account, find the name and password of your Salesforce account.
    Note: To create a test account in Salesforce without charge, rather than use your business account, register for a Developer account from the URL https://developer.salesforce.com instead of a Trial account. If you connect to App Connect with a Trial account, the Salesforce events don't work.

Create the flow for the API

  1. On the Dashboard, click Create > Flows for an API.
  2. 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
  3. In the Model name field, enter a name for your model that reflects the type of object that your API works with.

    The API flow that you're building creates a customer in Salesforce. Therefore, in the Model name field, type Customer.

  4. Click Create model. The Customer model panel opens with a Properties tab and an Operations tab.
  5. On the Properties tab, add properties that define the structure of the object that the API works with.
    1. You want the API to create, update, and retrieve a customer. Therefore, add the following properties that identify customers to the Customer model. Each property has a type of String by default.
      CustomerID
      FirstName
      LastName
      Email
      Figure 2. Adding properties for the API.
      Adding properties for the API.
      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.
      • The name must contain only letters, numbers, or the underscore character.
      • The name must contain at least 2 characters.
      • The name must begin with a letter or an underscore.
      Tip: 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) is selected as the ID property. Because you want your flow to return a customer ID when you create the customer object, leave this property as the ID property.
      Note: Your flow must return the ID property when it creates an object. Or the ID property must be sent in a request to update or retrieve an object by using its ID. You can set only one property as the ID property.

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

  6. To define how the API interacts with the object, click Operations. On the Operations tab, you can define the following actions.
    • Create an object.
    • Retrieve an object by using its unique ID or by using a filter.
    • Replace or create an object by using its ID or a filter. This action replaces an object if it exists, or creates it if it doesn't exist.
    Note: You can also define your own operations by clicking Add a custom operation. Custom operations have the following restrictions:
    • 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, see Create your own custom HTTP operations on API flows.

    1. Select Create Customer.
      Figure 3. Adding the Create Customer operation
      Selecting the Create Customer operation
  7. To create a flow that defines how the Create Customer operation works, click Implement flow. You see a basic flow in the flow editor with a Request node, a Response node, and an add node icon Icon to add a node to a flow to add one or more target applications. Notice the structure of the Request body example, which is constructed from the properties in your model with some sample data.
    Figure 4. An example of a request body from the Customer model with some sample data
    Request body example from the Customer model, with some sample data
  8. To add the target application to the flow, click Add node (+).
  9. Select Salesforce > Contacts > Create contact.

    If App Connect isn't already connected to Salesforce, click Connect and provide the details of your Salesforce account. For more information, see How to use IBM App Connect with Salesforce.

  10. Map the fields from the request into the Salesforce Create contact action as follows.
    • Click in Account ID, click Insert a mapping Insert a mapping icon, then select CustomerID from the Available inputs list.
    • In Last Name, type last, then select LastName from the list.
    • In First Name, type fir, then select FirstName from the list.
    • In Email, type em, then select Email from the list.
    Figure 5. Map fields from the request into the Salesforce Create contact action
    Mapped fields for the Salesforce action
  11. 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.
  12. Click the Response node in the flow to define the response that is returned when the operation completes successfully. Map the available fields from the Salesforce Create contact action to the response as follows.
    • For the mandatory response field CustomerID, map the Salesforce field Contact ID. If needed, map other fields to return their values in the response.
      Figure 6. Map the available fields from the Salesforce Create contact action 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).
  13. Click Done to return to your model.

Conclusion

You created an API. You can test the API by clicking Test API. For more information, see Testing flows during development. You can start and stop an API flow on the App Connect Designer dashboard in the same way as any other flow. You can open an API while it's running, but you must stop it before you can edit it.

Figure 7. The flow tile on the App Connect Designer dashboard
The tile for the running API flow.

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