Adding GraphQL endpoints to your Adalo app lets you fetch precise data, reducing unnecessary requests and improving performance. This guide walks you through the process of integrating GraphQL into Adalo using External Collections.
Key Steps:
- Prepare Your Endpoint: Test your GraphQL API for accessibility, JSON format, and authentication.
- Create an External Collection: Connect your GraphQL endpoint in Adalo and configure authentication.
- Define Queries and Mutations: Use GraphQL queries to fetch data and mutations to update or create records.
- Set Headers and Parameters: Ensure proper headers (e.g.,
Authorization) and specify JSON keys for data parsing. - Test and Deploy: Bind data to app components, test functionality, and publish your app.
Adalo supports numeric IDs for records and has a rate limit of 5 requests per second. Following these steps ensures smooth integration and optimized app performance.
5-Step Process to Add GraphQL Endpoints in Adalo
Step 1: Prepare Your GraphQL Endpoint
Before diving into the integration process, ensure your endpoint is functioning correctly. Think of this as your pre-flight checklist: confirm the endpoint is accessible, returns data in proper JSON format, and accepts valid authentication.
Verify Endpoint Accessibility
Start by testing your endpoint using tools like GraphiQL, GraphQL Playground, or Postman. Typical endpoint URLs might look like this: https://api.example.com/graphql, /api/graphql, or /v1/graphql.
Send a simple query, such as { __typename }, to verify the endpoint's reachability and confirm it responds correctly. Next, check if schema introspection is enabled by querying __schema. This will give you a detailed map of the available types, fields, and operations, helping you understand what data you can request.
Be aware that GraphQL often returns an HTTP 200 OK status even when errors occur. Errors will appear in the errors array of the response. For example, try querying an invalid field to see if the response includes a GRAPHQL_VALIDATION_FAILED error.
Finally, confirm the response is structured in the JSON format that Adalo requires. Pay close attention to the top-level key where your data resides, such as data, records, or resource. This detail is critical when setting up your External Collection in Adalo.
Once you’ve confirmed the endpoint is accessible and formatted correctly, move on to validating your authentication setup.
Gather Authentication Credentials
Most secure GraphQL endpoints require authentication, and there are a few common methods: API Keys, Personal Access Tokens (PAT), or OAuth 2.0 tokens (often in JWT format). These credentials are typically added to HTTP headers like this:
Authorization: Bearer YOUR_TOKEN_HERE
Here’s a quick reference for some common services:
| Service Provider | Credential Type | Header Key | Value Format |
|---|---|---|---|
| Airtable | Personal Access Token | Authorization | Bearer [Token] |
| DreamFactory | API Key | X-DreamFactory-API-Key | [Key] |
| Any GraphQL API | JWT / OAuth Token | Authorization | Bearer [Token] |
Where you get these credentials depends on your API provider. For Airtable, you’ll find the option to create a Personal Access Token in the Developer Hub under your account settings. Make sure to assign the necessary scopes (like read/write access) and specify which databases the token can access. For DreamFactory, API keys are created and managed within the platform using Role-Based Access Controls.
To test your authentication, include the credentials in your request headers when sending queries through GraphiQL or Postman. If the endpoint returns data instead of an authentication error, you’re good to go.
Step 2: Create an External Collection in Adalo
Now that your GraphQL endpoint is verified and you have your authentication credentials ready, it’s time to connect your data source to Adalo. This step essentially turns your external data into a collection that functions seamlessly within your app.
Navigate to External Collections
Start by opening the Adalo Builder. On the left-hand toolbar, click the Database tab (look for the database icon). Under the "External Collections" section, select + Add Collection. Give your collection a name that reflects the type of data you'll be working with, like "Products" or "Users." This naming step helps keep everything organized, especially as you add more integrations later.
Once named, you’ll move on to configuring the endpoint and authentication details.
Configure Endpoint and Authentication
In the setup screen, enter your GraphQL endpoint in the Base URL field (e.g., https://api.example.com/graphql). Then, set up your authentication by clicking + Add Item under Headers. Add a header with the name "Authorization" and the value Bearer [Your_Token]. Be sure to include a space after "Bearer."
Adalo supports both Basic Auth and OAuth for external collections. For most GraphQL endpoints, you’ll likely use Basic Auth with an API key or an OAuth token. Keep in mind that Adalo expects your GraphQL endpoint to return data in standard REST-like JSON format.
After completing the authentication setup, you’ll need to enable JSON response parsing.
Enable JSON Response Parsing
GraphQL responses often nest data within specific JSON keys like data, records, or items. To help Adalo correctly interpret this structure, specify a Results Key in the "Get All Records" section of your endpoint configuration. This tells Adalo where to look for the array of records in the JSON response.
Make sure at least one record exists in your data source during this step. When you click Run Test, Adalo will analyze the JSON response and automatically generate corresponding properties for your app, such as Text, Number, or Date fields.
It’s worth noting that Adalo currently only supports numeric IDs in External Collections. If your GraphQL endpoint uses text-based IDs, UUIDs, or IDs with special characters, you may need to use a workaround. A proxy service like n8n.io can help by converting GraphQL responses into an Adalo-compatible JSON format.
Step 3: Define GraphQL Queries and Mutations
With your endpoint verified and external collection configured, it's time to link GraphQL operations to Adalo's data actions. This step is crucial for connecting your app's interface to the GraphQL backend, allowing seamless data retrieval and updates through queries and mutations.
Define Queries for Data Retrieval
Adalo's External Collections support five key actions: Get All, Get One, Create, Update, and Delete. For GraphQL, these actions all use the same base URL and require the POST method - even when retrieving data. Instead of traditional query strings, GraphQL embeds its queries directly in the request body.
For example, when setting up the "Get All Records" endpoint, format your JSON body like this:
{"query": "query { users { id name email } }"}.
Set the Results Key to align with your API's response structure. This could be something like data.users or just users, depending on the API's design.
After configuring the endpoint, click Run Test to generate collection properties. Make sure your external data source includes at least one complete record before testing. If a field is empty across all records, Adalo won't detect that property during the setup.
Once your queries are in place, it's time to move on to configuring mutations for data updates.
Configure Mutations for Data Updates
Mutations are used for creating, updating, and deleting records in your GraphQL backend. For the "Create a Record" action, format your mutation in the request body like this:
{"query": "mutation CreateUser($name: String!, $email: String!) { createUser(name: $name, email: $email) { id name email } }", "variables": {"name": "VALUE", "email": "VALUE"}}.
Replace "VALUE" with Magic Text to dynamically insert data from your app.
When setting up the "Update a Record" action, the structure is similar, but you'll also need to reference the specific record ID to modify. Even though GraphQL uses POST for all operations, you can adjust the method to PATCH if you're only updating certain fields.
After configuring each mutation, run a test to ensure the response structure matches your expectations. Keep in mind that Adalo processes over 20 million data requests daily, but there is a platform rate limit of 5 requests per second. If you exceed this limit, you'll encounter a 429 status code.
Once your queries and mutations are tested and working, you're ready to move on to configuring headers and parameters in the next step.
sbb-itb-d4116c7
Step 4: Configure Request Headers and Parameters
With your queries and mutations ready, the next step is to set up the appropriate headers and parameters to ensure seamless communication with your GraphQL endpoint. This step is crucial for verifying your identity and formatting your data correctly, as missing or incorrect headers can cause your requests to fail.
Add Required Headers
For every GraphQL request in Adalo, you’ll need at least two headers: Content-Type and Authorization. Set the Content-Type to application/json to indicate the format of your data. The Authorization header should include your API key in the format Bearer [Your_API_Key], making sure to leave a space between "Bearer" and your token.
"All requests to the Adalo API will need to contain the following two headers: Authorization: Bearer [Your App's API Key] Content-Type: application/json"
– Adalo Resources
Depending on your backend, you might need additional headers. For instance, if you’re working with DreamFactory, you’ll need to include an X-DreamFactory-API-Key header with your specific key. To add these headers in Adalo, navigate to the "Headers and Queries" section, click +Add Item, and manually input the header name and its value.
Define Query Parameters
While GraphQL typically sends data in the request body, some APIs require query parameters for tasks like filtering, pagination, or even authentication. To add these parameters in Adalo, click Add Item under External Collections and input the required parameter names and values. Some APIs may use query parameters for authorization instead of headers, so it’s essential to consult your API’s documentation to ensure accuracy.
If your endpoint returns nested data, you’ll need to specify a Results Key (e.g., data.users or records) to help Adalo locate the specific JSON key containing your records. This step is especially important for GraphQL responses structured with multiple layers of data.
Run Tests to Validate Configuration
Once everything is set up, use the Run Test feature to send a live request to your endpoint. A successful test will allow Adalo to automatically detect and map the data properties based on the API’s response. Before running the test, make sure your external data source includes at least one complete record for validation.
If the test fails, check the error message displayed in the Adalo modal. Common issues include authentication errors, malformed JSON, or incorrect URLs. The Show Full Response option can help you inspect the raw data and verify that all necessary fields are being returned.
After confirming that your settings work correctly, you’re ready to move on to binding data in the next step.
Step 5: Test, Bind, and Deploy Your App
Now that your GraphQL endpoint is set up and tested, it’s time to connect your data to your app’s interface and get it ready for deployment. With everything configured, you can seamlessly bind your data to your app’s UI. External Collections function just like native data sources in Adalo.
Bind Data to Screens and Components
To display data from your GraphQL endpoint, start by adding a List component to your app. Set its data source to your External Collection. During the "Run Test" phase, Adalo automatically detects the properties available in your API response, making them accessible through Magic Text.
To map specific data fields from your GraphQL response to your app's UI, tap the Magic Text icon in the component settings (e.g., Title, Subtitle, or Image) and select the corresponding JSON keys. For detail screens, you can link list items to new screens by using the following steps: Add Action > Link > New Screen. Adalo will automatically pass the "Current [Collection Item]" data to the new screen, allowing you to use Magic Text to display specific details from the selected record.
If your GraphQL schema changes or you add new fields, simply go back to the Database tab, update the External Collection settings, and re-run the connection test to make the new fields available in the editor.
Preview and Publish the App
Click the Preview button to ensure your data loads correctly and all actions work as expected. Once you’ve confirmed everything is functioning, you can publish your app to the web, iOS, and Android using Adalo's single-codebase system. Any updates you make will automatically reflect across all platforms, so there’s no need to rebuild for each one. After publishing, take advantage of Adalo's built-in diagnostics to keep an eye on performance.
Monitor Performance and Debug Issues
Once your app is live, Adalo's X-Ray tool can help you analyze performance and troubleshoot any integration issues. Keep an eye on request frequency to avoid hitting API rate limits. Some common issues to watch for include timeout errors caused by large payloads and authentication problems due to missing or incorrect headers. Regular monitoring will ensure your app runs smoothly for users.
Conclusion
Adding GraphQL endpoints to your Adalo app simplifies data fetching and reduces the need for extensive custom coding. By following these five steps - preparing your endpoint, setting up an External Collection, defining queries and mutations, configuring headers, and testing thoroughly - you can connect your app to robust external backends while keeping your frontend efficient and user-friendly.
Organizations have reported saving up to 15 hours per week on manual data entry and cutting costs by 65% compared to custom development.
"GraphQL allows you to answer API queries using your pre-existing data... it offers customers the power to request only the information they want and nothing more." - n8n
For better performance, consider using PATCH instead of PUT, apply filters to stay within the 5-requests-per-second rate limit, and use Adalo's X-Ray tool to identify potential issues. These small adjustments can significantly improve your app's responsiveness and make the investment in Adalo's Professional plan worthwhile.
The Adalo Professional plan, starting at $52 per month when billed annually or $65 per month on a monthly basis, provides access to External Collections. This unlocks immediate savings in engineering time and ensures your app scales effortlessly. With GraphQL, your data integrates seamlessly into lists, forms, and actions - no coding required.
FAQs
How can I make sure my GraphQL endpoint works properly with Adalo?
To make sure your GraphQL endpoint functions smoothly with Adalo, start by confirming it supports standard GraphQL queries and mutations. Run tests to ensure it delivers properly structured responses that meet Adalo's integration standards.
It's also important to verify that the endpoint is accessible and set up to manage the specific data requests your app will make. By following the step-by-step instructions in the guide, you'll be able to configure and test the endpoint for a seamless integration experience.
What types of authentication can you use to connect GraphQL endpoints in Adalo?
Adalo offers support for multiple authentication methods when connecting to GraphQL endpoints. These include API keys, OAuth, and other credential-based approaches. The choice of method depends on the specific requirements of the API you’re working with.
As you set up the connection, make sure to carefully follow the authentication guidelines provided by the API provider. Additionally, take steps to securely store and handle any credentials or tokens within your app to protect sensitive information.
What are the best ways to improve app performance when using GraphQL with Adalo?
To get the best performance out of your app using GraphQL in Adalo, it’s all about refining your data workflows and cutting down on unnecessary processing. By automating repetitive tasks with workflow tools, you can simplify data management and boost efficiency.
Another approach is connecting your app to external databases, especially if you're working with large datasets. This can help reduce load times and keep your app running smoothly. Focusing on these strategies will ensure your app delivers a faster and more dependable experience for users.
Related Blog Posts
