# API Recipe Walkthrough
Ready to make your own API recipe? In this guide, we'll walk you through an example using Salesforce.
Our goal is to automate creating an opportunity in Salesforce and then expose it as a REST endpoint. External business partners and internal stakeholders can use this endpoint to access and consume data without requiring access to a Workato account.
# Step 1: Create The Recipe
In this step, you'll create the recipe and select its starting point.
Create a new recipe and give it a name.
Select a folder to contain the recipe.
Click Build an API endpoint as the starting point.
Click Start Building.
When the Build an API endpoint starting point is used, Workato will automatically create a recipe with a New API request trigger and a Response to API request action.
# Step 2: Define The Recipe's Trigger
Next, you'll define the request and response structures for the endpoint by defining the New API request trigger parameters. Defining the trigger has two steps:
# Step 2.1: Define The Endpoint's Request Structure
In this step, we'll define the parameters for requests made to the endpoint. The request schema determines the fields that are shown and must be defined when an action is created in the API recipe.
Click the trigger to open its Setup tab.
Open the Request tab if it's not open already.
In the Content type field, select the type of data the endpoint should accept. For example, selecting application/json means the endpoint would expect and accept valid JSON data in a request.
In the Request header section, define the parameters that should be in the headers of requests sent to the endpoint.
In the Request schema section, define the schema of request bodies sent to the endpoint. You can either upload a sample JSON file or enter the fields manually.
In this example, our schema would contain the fields necessary to create a Salesforce opportunity.
# Step 2.2: Define The Endpoint's Response Structure
After you've defined the structure for requests, move on to the endpoint's response structure. The response structure determines the outputs returned by the API recipe and their respective fields.
For example, if you wanted your endpoint to inform users when an opportunity is successfully created, you could add a response (200 - Created) that does that. The response could contain information about the opportunity, such as its ID, creation time, and so on.
You can also define Error responses in this section in case the API recipe action isn't successful.
Open the Response tab, if it's not open already.
In the Content type field, select the type of data the endpoint should accept.
In the Response headers section, define the parameters that will be present in response headers sent from the endpoint.
In the Responses section, select Add response.
In the Response #1 section, specify a name for the response.
In the HTTP status code field, set whether the response code is standard or custom.
- If you select Standard response, choose an HTTP status code from the picklist.
- If you select Custom response, enter a custom HTTP status code. You can specify response codes from 2xx to 5xx.
In the Response schema section, define the schema of response bodies sent from the endpoint. You can either upload a sample JSON file or enter the fields manually.
In this example, we could add an ID field to represent the ID of the newly created Salesforce opportunity.
# Step 3: Add Steps To The Recipe
Next, we'll add actions to the recipe. As per our best practices for creating recipes, we're going to add these blocks:
- Monitor - Think of this block as the success response. If actions in it are executed without error, the recipe will end here.
- On Error - If the Monitor block returns an error, actions in this set will be executed.
# Step 3.1: Define The Monitor Block
In the Monitor block, add the desired action. In this example, we'll add an action that creates a new opportunity in Salesforce (Action in an app > Salesforce > New opportunity.)
Map the appropriate data to the action. We can manually map the data from the recipe's trigger to the required input of the Salesforce action or use the Group map data to do the mapping for us automatically.
After you're finished defining the action(s), click the Return action. Defining the Return action ensures our API endpoint returns a response that indicates if the actions in the Monitor block were successful.
To define the Return action:
Select a Response. For example, if the opportunity was successfully created in Salesforce, we could select Created.
In the Response schema section, map the appropriate data to the schema's fields.
For example, we want to return the newly created opportunity's ID in the response, so we'll map our ID field to the Object ID datapill returned from the Create Opportunity in Salesforce action.
# Step 3.2: Define The On Error Block
The last step is to define the On Error block, which will run if the action(s) in the Monitor block - in this case, that's the Create an opportunity in Salesforce action - are unsuccessful.
Error responses enable your endpoint to provide useful information when something goes wrong, allowing for more targeted troubleshooting.
For example, if the opportunity isn't successfully created due to Salesforce's API experiencing an outage, you could add a response that indicates this.
# Step 4: Save And Test The Recipe
Save and test your recipe as you go! We recommend building recipes in small steps to make it easier to troubleshoot any issues you encounter.
# What's next?
NEED TIP-TOP API PERFORMANCE?
Using the Jobs data retention recipe setting, you can enable zero logging and improve performance for your API recipes. Note that there are some trade-offs.
Check out the Defining data retention for recipes for more info.
Congrats on creating an API recipe! Check out what else you can do with these other resources:
Last updated: 8/18/2023, 12:13:12 AM