Ben Busse - July 10, 2013
BenBusse

Developers often ask how to query related data with DreamFactory’s REST API. For example, how do you fetch a record and its related children as JSON in a single API call? In this post, we’ll demonstrate related data queries with a real example.

Also check out these related blog posts. Why We Like Swagger for API Docs covers how to use our live API docs to explore the API. To learn more about how Modus Create built the Address Book application with DreamFactory, check out the DreamFactory & Modus Create Case Study.

Read more about Swagger security: Share API Docs Securely

1. To follow along, you’ll first need a DreamFactory account. You can sign up for an account here.

2. Log in to your account, go to your DSP admin console, and click on the Applications tab on the left hand side.

Swagger blog 1

3. Click ‘Import New App’ in the upper right corner and choose the Address Book sample app. This contains related schema for both parent-child and related records via junction table relationships.

Swagger blog 2

Once you’ve imported the application, you can preview it in your DSP.

Swagger blog 3

Use your DSP admin user name and password to log in to the Address Book app and see the app.

Swagger blog 4

4. Go to the ‘Manage Schema’ and ‘Manage Data’ tabs to peruse the table layouts and sample data if you wish.

Swagger blog 5

The Contacts table stores basic information about each contact. ContactInfo stores contact information like phone, email, and address. A Contact can have many child ContactInfo records.

The ContactGroups table stores information about Groups. A Contact can belong to any number of Groups. ContactRelationships is a junction table that stores the associations between Contacts and Groups.

Swagger blog 6

5. Click ‘API Documentation’ to load Swagger REST API interface.

Swagger blog 7

Select ‘schema’ -> GET /schema/{table_name} to expand.

Swagger blog 8

In the ‘table_name’ field type ‘Contacts’ and click the ‘Try it out’ button.

Swagger blog 9

In the Response Body, you’ll see the field section and the related objects. Note the relationship names in the JSON (highlighted in red below) and the key value pairs that describe each relationship.

Swagger blog 12

6. Back in the main Swagger API Documentation, Select ‘db’ -> GET /db/{table_name}.

Swagger blog 10

In the ‘table_name’ field type ‘Contacts’. In the ‘ids’ field enter a couple of ids from the sample data e.g. 1,3). In the ‘related’ field type ‘ContactInfos_by_contactId,ContactGroups_by_ContactRelationships’. This will pull both the child info records and the groups related by junction. Click ‘Try it out’ and note the URL call and results.

Swagger blog 11

The Request URLlooks like this, where ‘foo’ is the name of your own DSP.

https://dsp-foo.cloud.dreamfactory.com/rest/db/Contacts?ids=1%2C3&related=ContactInfos_by_contactId%2CContactGroups_by_ContactRelationships

Take a look at the Response Body and notice the JSON structure for child data, in this example multiple ways to contact a person. Also notice how the JSON encodes the associations between a Contact and zero or more Contact Groups to which the Contact belongs.

Swagger blog 13

We hope this overview has shown you how to make sophisticated queries with DreamFactory’s REST API! Please comment if you have any feedback or questions.

Related reading: What is API Access?