API management use case: HR operations

The system aims to streamline the process of accessing and updating employee data by integrating an API that connects the company’s employee management portal with the backend HR system. The objective is to facilitate HR managers' retrieval and management of employee details such as job titles, gender, work emails, and other relevant personal information directly through an API interface.

✅ Prerequisites

• Access to Quickwork’s API Management tool.
• If you would like to try out this journey, then you need a Google Sheets, Employee Details with the employee details.

Building the journey using API management

1. Log in to your Quickwork account. Go to Tools, then select API Management.

2. Build a callable journey:

   1. Go to Folders and click the + Create Journey button.
   2. Select Callable Journey - New call as the trigger to accept inputs via API.
   3. Enter Name as Callable-Employee Fetch to easily identify its purpose. Ensure that the journey is saved under this name for consistency.
   4. Set both the Request type and Response type to application/JSON, accommodating JSON formatted data.
   5. In the Input field, define JSON structure {"ID":"emp001"} and Output as {"Name":"emp001","Email":"[email protected]","Gender":"Male","Role":"Demo"} These values interact with Postman (or the employee management portal in a real-world scenario) to fetch specific employee details.
      
   
   
   6. Set up actions to fetch employee data. Choose Google Sheets as the app you want to configure for the action and set the action to Search cell using query to allow for specific cell searches within a Google Sheet.
   7. Click on the Spreadsheet drop-down menu and select Employee Details.
   8. In the Query String field, input your specific query. For instance, to find a cell where the column 'A' equals a certain ID, enter select* where A='{ID}’. Here, ID is the specific ID datapill from the Data Tree Output.
   9. Provide a JSON format Sample Response that you expect to receive from this query, {"Name":"emp001","Email":"[email protected]","Gender":"Male","Role":"Demo"}. This sample assists in mapping and appears as data pills in the Data Tree Output for subsequent actions.
      
   
   
   10. Add a new action step using the Callable Journey again to process the return and choose the action as Return response.
   11. Set the Response type to Success and drag and drop the Name, Email, Gender, Role data pills from Google Sheets | Search cell using query in Data Tree Output, to the Name, Email, Gender, Role input fields. This dynamic response ensures personalized interaction.
       
   
   
   12. Save all configurations and start the journey by clicking Save & Start.

3. Create an API endpoint:

   1. If creating an API for the first time, establish a unique Path Prefix to standardize all API endpoints.
   2. Go to the API Collections tab and select the + Create new API Collection button. Provide details like Name, Version, Description, and Path. Defining the path will automatically append to endpoint URLs, incorporating the prefix and version number.\
      
   
   
   3. Within the created collection, add a new endpoint for fetching employee details.
   4. Enter the Name, select the callable journey, and set the request Method to POST, enter the Path and keep the CORS empty.\
      
   
   5. The endpoint can be accessed at the created URL.

4. Manage clients and access profiles:

   1. Under the Clients tab, create a new client to represent users who will access the API.
   2. Create access profiles under each client, specifying which API collections are accessible.
   3. Configure rate limits and usage quotas to manage the load and ensure fair usage of the API resources, if required.

5. Test the API:

   1. Use the API testing tool Postman to simulate API calls. Select the method, copy the API URL and enter it into Postman.
   2. In the Headers section, enter APIkey in the KEY column and paste the previously copied API key from the client access profile into the VALUE column to authenticate the request.
   3. Switch to the Body tab and select raw with format set to JSON.
   4. Validate the API responses against known outputs to ensure accuracy. Enter the JSON body. For example, {"ID":"Q001"} to match the input configured in the API.
   5. Click the Send button to execute the API call.
   6. Observe the response displayed in Postman. If configured correctly, you should see fetched employee details in the response.
      
   

5. Deploy and monitor the API:
   1. Deploy the API in a staging environment for live testing.
   2. The company's employee management portal can be integrated with this API for accessing employee details. Monitor API usage and performance through Quickwork’s API Management tool.
   3. Collect feedback from HR managers and make necessary adjustments before full-scale deployment.

❓ Troubleshooting

• API not responding or errors on execution: Ensure the API key is correctly entered in the headers section.
• Incorrect data being fetched:
  • Double-check the JSON structure defined in the Input field to ensure it matches the expected format in Postman.
  • Validate the query strings used in the Google Sheets action to ensure they correctly reference the desired cells and data formats.
• Callable journey failures:
  • Review the callable journey configuration, particularly the input and output settings, to ensure they align with the data input in Postman.
  • Check for any errors in the data pills placement in the response setup.
• Rate limit and quota issues:
  • Adjust the rate limits and quotas as necessary based on usage patterns and feedback from HR managers.
• Security best practices: Implement strict CORS policies to prevent unauthorized data access.
• Error in Sample Response step: Enter the sample response in JSON format without a full stop at the end.

📚 Additional resources

API terminologies
Building a callable journey for API management
Creating and testing API endpoints
Creating and managing client access
Testing and sharing the API
Securing API access with rate limits and quotas