Testing & sharing the API

✅ Prerequisites

• Completion of API endpoint creation and client setup with a generated API key.
• Basic understanding of using API testing platforms like Postman.

Testing the API using Postman

1. Sign in to Postman.

2. Navigate to New Request in the Send an API request section.

3. Select POST as the method to match the API endpoint setup. Ensure consistency in the HTTP method used when creating and testing the endpoint to avoid errors.

4. Enter the copied URL of the API into Postman.

5. Configure request headers:

   1. In the Headers section, enter APIKey in the KEY column.
   2. Paste the API key previously copied from client access profile into the Value column to authenticate the request.
      
   

6. Set up the request body:

   1. Switch to the Body tab and select raw with format set to JSON.
   2. Enter the JSON body. For example, { "name": "John Doe" } to match the input configured in the API.

7. Send the request:

   1. Click the Send button to execute the API call.
      
   
   
   2. Observe the response displayed in Postman. If configured correctly, you should see the 'Hello world, {user}' message.
      
   

8. Verify journey execution:

   1. Return to the Quickwork platform and check the journey linked to the API.
      
   
   
   2. A successful response is logged, confirming the API and journey are interacting correctly.

   Sharing the API

   1. Check that the API endpoint and the API key are correct.

   2. Distribute API access:

      1. In Postman, click the </> icon on the right side to generate a cURL command or code snippet for the API request.\
         
      
      

      b. Share the URL snippet, API endpoint, and API key with the intended users or customers via email or any preferred communication method.

   3. Keep records of whom the API details are shared with to manage access and troubleshoot potential issues.

   ❓ Troubleshooting

   • API key not recognized: Ensure the API key is copied correctly without any leading or trailing spaces.
   • Access denied errors:
     • Confirm that the access profile includes the necessary API collections and that the endpoint methods (GET, POST, etc.) match those configured in the access profile.
     • Review IP Whitelist settings to ensure the requests are made from allowed IPs.
   • Rate limit and quota errors:
     • Monitor usage to ensure you are not exceeding the configured rate limits or quota. Adjust these settings in the access profile as needed based on usage patterns.
     • If encountering rate limits frequently, consider optimizing API calls or increasing the limit based on business needs.

• Client or endpoint configuration issues:
  • If endpoints are not responding as expected, review the endpoint configuration for errors in the path, method, or linked callable journey.
  • Ensure that CORS settings are correctly configured to allow requests from the necessary domains.

✏️ Tips and recommendations

• Always use secure methods to share API keys. Avoid exposing keys in public forums or insecure platforms.
• Regularly monitor API usage and responses to ensure the API performs as expected and detects unauthorized access.

📚 Additional resources

API terminologies
Building a callable journey for API management
Creating and testing API endpoints
Creating and managing client access
Sample use case on API management: HR operations
Securing API access with rate limits and quotas