This guide walks you through connecting to REST APIs in Matik and creating dynamic content that pulls data from these APIs.
Setting Up Your REST API Connection
When adding a new REST API data source to Matik, you'll need to provide two key pieces of information:
REST API Base URL
- This is the main URL for the API you're connecting to (example: `https://api.example.com` or `https://company.com/api/v1)
- This serves as the foundation for all API calls Matik will make
Test URL (Optional)
- A specific endpoint path to verify your connection is working (example: `/health`, `/status`, or `/users)
- This is combined with your base URL to test the connection
- When you click "Test Connection", Matik will make a GET request to this endpoint
Authentication Methods
Matik supports three different authentication methods for REST APIs. Choose the method that matches your API's requirements:
1. Access Via Login (Basic Authentication)
Use this method when your API requires a username and password for authentication.
- Enter your API username
- Enter your API password
- Matik will use these credentials for basic HTTP authentication with every API request
Best for: APIs that use standard username/password authentication
2. Access Via Auth Token
Use this method when your API requires an authentication token or API key.
- Add a description that explains what token users need to provide
- Enter your test access token for connection testing
- Users will be prompted to provide their own token when using this data source
Best for: APIs that use API keys, bearer tokens, or other token-based authentication
3. Access Via OAuth2
Use this method for APIs that implement OAuth 2.0 authentication flow.
- Client ID: Copy from your API provider's OAuth app setup
- Client Secret: Copy from your API provider's OAuth app setup
- OAuth Scopes: Optional permissions your app needs (separate multiple scopes with spaces)
- Response Type: Usually "code" for standard OAuth flow
- Authorization Server Prompt: Controls how users are prompted to authenticate:
- Consent: Always ask for permission
- Login: Always require login
- None: Skip prompts if possible
- Select Account: Let users choose which account to use
- Login URL: The authorization endpoint from your API provider
- Token URL: The token endpoint from your API provider
Important: When setting up OAuth with your API provider, use the redirect URI that Matik provides in the setup form.
Best for: APIs that use OAuth 2.0 standard authentication
Testing Your Connection
After configuring your base URL, test URL, and authentication method, use the "Test Connection" button to verify that Matik can successfully communicate with your API. This helps ensure your configuration is correct before you start creating dynamic content.
Querying a REST API
Once your REST API is connected, you can create dynamic content that pulls data from your API endpoints.
Basic Query Setup
HTTP Method Selection
- Choose between GET and POST requests
- GET is used for retrieving data
- POST is used when you need to send data in the request body
API URL Configuration
- Enter the specific endpoint path you want to query
- This gets combined with your base URL from the connection setup
- You can include inputs using &: and dynamic content using curly braces (e.g., `/users/&:user_id` and `/users/{{user_id}}`)
Advanced Features
Request Body (POST requests only)
- When using POST, you can include a JSON request body
- Use the JSON editor to structure your request data
- Inputs and dynamic content can be included in the request body using &: and dynamic content using curly braces (e.g., `/users/&:user_id` and `/users/{{user_id}}`)
Asynchronous Job Polling
- Enable this feature when your API creates background jobs that need time to complete
- Configure the polling endpoint that Matik will check for job status. You can template this endpoint using JQ to pull fields from the initial request's response (e.g. `/reports/get_status/{.id}`)
- Set the polling interval (how often to check) and timeout (maximum wait time)
Define success criteria to determine when the job is complete: - HTTP Status Code: Job is complete when a specific status code is returned
- Response Field: Job is complete when a specific field in the response matches your criteria. Use JQ to set a condition that will evaluate to true or false based on the polling endpoint response (e.g. `.success == 'true'`)
Working with API Results
- Result Formatting
- After running your query, you can select which fields from the API response to include
- Use the JQ filtering language to transform and filter your data
- Map API response fields to specific uses in your presentations
Understanding JQ (JSON Query Language)
JQ is a powerful tool for processing JSON data that allows you to extract, filter, and transform information from API responses. Learn more about JQ syntax and capabilities in the official JQ documentation
JQ Query Generator Tool
Matik includes a built-in JQ query generator to help you create queries without needing to learn the full JQ syntax:
- Access the Tool: Click the code icon (</>) next to certain input fields to open the Raw API Response Data panel
- Test Your Query First: The tool requires you to test your API query to have response data available
- Interactive Query Generation:
- Hover over any value in the JSON response to see the automatically generated JQ query
- Click on string, number, boolean, or null values to select that query
- The suggested query appears in the input field above the JSON data - Manual Editing: You can also manually edit the suggested query before applying it
Using the JQ query generator:
- Mouse over different parts of your API response to see how to extract that data
- Values like strings, numbers, and booleans are clickable and will automatically generate the correct JQ path
- The tool shows you the exact JQ syntax needed to extract any field from your API response
- Use this tool to learn JQ syntax by seeing how different selections translate to JQ queries
Best Practices
- Start Simple: Begin with basic GET requests to familiar endpoints before adding complexity
- Test Frequently: Use the connection test and query preview features to verify your setup
- Monitor Performance: Be mindful of API rate limits and response times
- Security: Only connect to trusted APIs and avoid exposing sensitive data
Getting Help
If you encounter issues with your REST API integration:
- Verify your base URL is correct and accessible
- Check that your API endpoints are properly formatted
- Ensure any required authentication is properly configured
- Test with simple queries before building complex dynamic content
Comments
0 comments
Please sign in to leave a comment.