JSON:API Query Builder

Acquia Source provides the JSON:API Query Builder to reduce integration time and enhance your experience with JSON:API. It helps you to build JSON:API queries, preview well-formatted real-time responses, and generate code samples.

JSON:API Query Builder interface

The following image illustrates the sections of the JSON:API Query Builder interface with labels:

The following table describes the sections labelled in the preceding image:

Label	Description
A	The Query Builder tab to build JSON:API queries with fields, filters, and relationships.
B	The Authentication tab to access examples of authentication when accessing the API from external applications.
C	The Examples tab to access examples of JSON:API queries.
D	The Entity Type and Bundle dropdowns to select the entity type and bundle for a query. For information about entity types and bundles, visit Entity types.
E

JSON:API Query Builder

Acquia Source provides the JSON:API Query Builder to reduce integration time and enhance your experience with JSON:API. It helps you to build JSON:API queries, preview well-formatted real-time responses, and generate code samples.

JSON:API Query Builder interface

The following image illustrates the sections of the JSON:API Query Builder interface with labels:

The following table describes the sections labelled in the preceding image:

Label	Description
A	The Query Builder tab to build JSON:API queries with fields, filters, and relationships.
B	The Authentication tab to access examples of authentication when accessing the API from external applications.
C	The Examples tab to access examples of JSON:API queries.
D	The Entity Type and Bundle dropdowns to select the entity type and bundle for a query. For information about entity types and bundles, visit Entity types.
E	The Page and Limit fields to set the pagination parameters for a query.
F	The Request History section to check the history of requests.
G	The Fields tab to add fields to a query. The Filters tab to add filters and filter groups to a query. The Includes tab to add relationships to a query. The Sort tab to add sort criteria  to a query. The </> tab to copy the API code example.
H	The Response section to review and copy the response.
I	The Execute Query button for manual execution of a query.
J	The Auto Execute checkbox for automatic execution of a query. After you select this checkbox and make any changes to your query, the response is immediately updated.
K	The Request URL section to copy the Request URL.

Building a JSON:API query

Use the following steps to build a JSON:API query:

1. Access your site.
2. In the left sidebar, click API > JSON:API Query Builder.

3. Select the entity type and bundle for your query.

   The Bundle dropdown shows the bundles that belong to the selected entity type.

4. Set the pagination parameters for your query:

   1. In the Page field, set the offset value.

      This value specifies the number of pages to be skipped. This is useful when implementing pagination.

   2. In the Limit field, set the page limit.

      This value specifies the maximum number of items to be returned in a single response. Setting a lower limit helps the server to respond faster.

5. Add filters and filter groups to your query:

   1. Click the Filters tab.

      This tab includes the Add Filter and Filter Groups (AND/OR logic) sections to add filters and filter groups respectively.

   2. In the Field dropdown, select the required field.

      This dropdown shows the fields that belong to the selected entity type and bundle.

   3. In the Operator dropdown, select the required operator.

   4. In the Value field, enter an exact value.

      For example, 1 or true.

   5. Click Add Filter.

      The filter is added to the Selected Filters section.

   6. Continue to add more filters, as required.

   7. In the Group Name field, enter a name for the filter group.

      This is an optional field. If you leave this field blank, a default name is used for the group.

   8. In the Logic dropdown, select AND or OR, as required.

   9. Click Create Filter Group.

Selecting fields for a query

When creating a JSON:API query, you can restrict the fields included in the response by selecting specific fields. This reduces the payload size and improves performance.

Use the following steps to restrict the fields included in the response:

1. Start building a query.

2. Navigate to the Fields tab.

   This tab shows the fields that belong to the selected entity type and bundle. For information about fields, visit Fields.

3. Click each of the fields that you want to add to your query.

Adding relationships in a query

The following is an example of how to add relationships in a JSON:API query to fetch media images as part of the response:

1. Start building a query.
2. In the Entity Type dropdown, select media.
3. In the Bundle dropdown, select image.
4. Click the Includes tab.

5. In the Includes (Relationships) section, click media_image.

   The media_image relationship is added to the query in the Request URL section:

   
6. Click Execute Query.

7. In the Response section, expand the included node and its subnodes to verify that all media images of your site are included in the query:

   

    

 

Building a JSON:API query

Use the following steps to build a JSON:API query:

1. Access your site.
2. In the left sidebar, click API > JSON:API Query Builder.

3. Select the entity type and bundle for your query.

   The Bundle dropdown shows the bundles that belong to the selected entity type.

4. Set the pagination parameters for your query:

   1. In the Page field, set the offset value.

      This value specifies the number of pages to be skipped. This is useful when implementing pagination.

   2. In the Limit field, set the page limit.

      This value specifies the maximum number of items to be returned in a single response. Setting a lower limit helps the server to respond faster.

5. Add filters and filter groups to your query:

   1. Click the Filters tab.

      This tab includes the Add Filter and Filter Groups (AND/OR logic) sections to add filters and filter groups respectively.

   2. In the Field dropdown, select the required field.

      This dropdown shows the fields that belong to the selected entity type and bundle.

   3. In the Operator dropdown, select the required operator.

   4. In the Value field, enter an exact value.

      For example, 1 or true.

   5. Click Add Filter.

      The filter is added to the Selected Filters section.

   6. Continue to add more filters, as required.

   7. In the Group Name field, enter a name for the filter group.

      This is an optional field. If you leave this field blank, a default name is used for the group.

   8. In the Logic dropdown, select AND or OR, as required.

   9. Click Create Filter Group.

      The filter group is added to the Selected Filters section.

   10. Continue to add more filter groups, as required.
   11. Continue to add more filters and add them to the required groups, as required.

6. Add relationships to your query:

   1. Click the Includes tab.

      This tab shows the relationships that belong to the selected entity type and bundle.

   2. Click each of the relationships that you want to add to your query.

   For more information, visit Adding relationships in a query.

7. Add sort criteria to your query:

   1. Click the Sort tab.

      This tab includes the Add Sort Criterion section.

   2. In the Field dropdown, select the required field.

      This dropdown shows the fields that belong to the selected entity type and bundle.

   3. In the Direction dropdown, select Ascending or Descending, as required.

   4. Click Add.

      The criterion is added to the Selected Sort Criteria section.

   5. Continue to add more sort criteria, as required.

8. Copy the API code example:

   1. Click the </> tab.

      This tab includes the API Code Examples section.

   2. In the Language dropdown, select the required language.
   3. Click Copy Code.
9. Click Copy URL to copy the Request URL.
10. Execute your query.
11. In the Response section, review the response and click Copy to copy the response.

Selecting fields for a query

When creating a JSON:API query, you can restrict the fields included in the response by selecting specific fields. This reduces the payload size and improves performance.

Use the following steps to restrict the fields included in the response:

1. Start building a query.

2. Navigate to the Fields tab.

   This tab shows the fields that belong to the selected entity type and bundle. For information about fields, visit Fields.

3. Click each of the fields that you want to add to your query.

Adding relationships in a query

The following is an example of how to add relationships in a JSON:API query to fetch media images as part of the response:

1. Start building a query.
2. In the Entity Type dropdown, select media.
3. In the Bundle dropdown, select image.
4. Click the Includes tab.

5. In the Includes (Relationships) section, click media_image.

   The media_image relationship is added to the query in the Request URL section:

   
6. Click Execute Query.

7. In the Response section, expand the included node and its subnodes to verify that all media images of your site are included in the query:

   

    

The filter group is added to the Selected Filters section.