Associations & Side-loading with the Admin API

The response JSON object contains a key for each collection you request. The value of each key is an array of objects. Using the “includes” param, you can easily side-load associated records. This allows you to request additional data in a single query and gives you control over the weight of the response. The “links” object in a response provides a list of available associations.

In this example, we’re requesting a list of suggestions and side-loading the associated forums and users:

  $ curl https://SUBDOMAIN.uservoice.com/api/v2/admin/suggestions?includes=forums,users \
       -H "Authorization: Bearer 096e8ae9c6a3c039"

(Simplified) Response:

  {
    "forums": [
      {
        "id": 2002,
        "name": "Product Ideas",
        "open_suggestions_count": 1,
        "suggestions_count": 1,
        "is_public": true,
        "created_at": "2017-01-20T14:24:45Z",
        "updated_at": "2017-01-20T14:24:45Z",
        "links": {
          "updated_by": null
        }
      }
    ],
    "links": {
      "forums.updated_by": {
        "type": "users"
      },
      "suggestions.category": {
        "type": "categories"
      },
      "suggestions.created_by": {
        "type": "users"
      },
      "suggestions.forum": {
        "type": "forums"
      },
      "suggestions.labels": {
        "type": "labels"
      },
      "suggestions.last_status_update": {
        "type": "status_updates"
      },
      "suggestions.parent_suggestion": {
        "type": "suggestions"
      },
      "suggestions.status": {
        "type": "statuses"
      },
      "suggestions.ticket": {
        "type": "tickets"
      },
      "users.current_nps_rating": {
        "type": "nps_ratings"
      },
      "users.external_users": {
        "type": "external_users"
      },
      "users.previous_nps_rating": {
        "type": "nps_ratings"
      },
      "users.teams": {
        "type": "teams"
      }
    },
    "list_meta": null,
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_pages": 1,
      "total_records": 1
    },
    "suggestions": [
      {
        "id": 303,
        "title": "Make the logo bigger",
        "body": "I love your logo but I can barely see it!",
        "created_at": "2012-07-19T14:23:16Z",
        "state": "published",
        "updated_at": "2017-01-20T14:24:47Z",
        "comments_count": 1,
        "links": {
          "forum": 2002,
          "category": null,
          "labels": null,
          "status": null,
          "parent_suggestion": null,
          "ticket": null,
          "last_status_update": null,
          "created_by": 1001
        }
      }
    ],
    "users": [
      {
        "id": 1001,
        "name": "Logo Fan",
        "email_address": "logofan@example.com",
        "avatar_url": "https://cdn.uservoice.com/pkg/admin/icons/user_80-fc2452956c9d66d679a429bd81acd3f3.png",
        "created_at": "2017-01-20T14:24:47Z",
        "updated_at": "2017-01-20T14:24:47Z",
      }
    ]
  }

Using the “links” property of the suggestion object, we can map the “forum” and “created_by” ids to the forum our suggestion belongs to and the user that created it.