Expanding responses — Masterconf API

A link to another object is its id. A registration names its event as "event": "EVT-…". With expand[], the API returns the whole object in its place, in the same request.

Expanding a field

Send expand[] with the name of the field. The object you get is the same as its own retrieve operation returns.

Request

curl

curl -G https://api.masterconf.com/v1/registrations/SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612 \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "expand[]=event"

JavaScript

const params = new URLSearchParams({
  "expand[]": "event",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations/SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations/SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612",
    params={"expand[]": "event"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

The fields you can expand are marked « expandable » in the reference: the event of a registration and of a call for papers, the call_for_papers and the event of a paper. Repeat the parameter to expand several fields.

In lists and searches

In a list or a search, prefix the field with data., because it applies to each object of data:

Request

curl

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30" \
  --data-urlencode "expand[]=data.event"

JavaScript

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
  "expand[]": "data.event",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30", "expand[]": "data.event"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Each linked object is read once per page, however many objects of the page share it.

Rules

One level. An expanded object is never expanded further.
The scope of the expanded object. Expanding an event also needs events_read. Without it, the request answers 403 api_key_scope_missing on expand.
A smaller page. A list or a search with any expand[] takes a limit of at most 20.
A field that cannot be expanded answers 400 parameter_invalid on expand.

Fields not included by default

Some fields cost one more read per object, so lists leave them out. An event’s languages and venue are always in GET/v1/events/{id}, but in GET/v1/events only when you ask for them:

Request

curl

curl -G https://api.masterconf.com/v1/events \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "expand[]=data.venue"

JavaScript

const params = new URLSearchParams({
  "expand[]": "data.venue",
});

const res = await fetch(`https://api.masterconf.com/v1/events?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/events",
    params={"expand[]": "data.venue"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

The reference marks these fields « not included in lists by default ». Ask for them only when you show them: each one adds reads to every page.