Files
relay/docs/GraphQL-ObjectIdentification.md
Greg Hurrell 565bdc8000 Clarify description of globally unique IDs
As written, this sentence was a little hard to read:

> A system without globally unique IDs can usually create one

Create one what? An ID, or a system?

I've reworded this to make it clear that the system can create IDs by
switching to the plural, and I've added a missing hyphen in
"type-specific".
2015-09-01 17:49:23 -07:00

2.4 KiB

id, title, layout, category, permalink, indent, next
id title layout category permalink indent next
graphql-object-identification Object Identification docs GraphQL docs/graphql-object-identification.html true graphql-connections

Both Faction and Ship have identifiers that we can use to refetch them. We expose this capability to Relay through the Node interface and the node field on the root query type.

The Node interface contains a single field, id, which is a ID!. The node root field takes a single argument, a ID!, and returns a Node. These two work in concert to allow refetching; if we pass the id returned in that field to the node field, we get the object back.

Let's see this in action, and query for the ID of the rebels:

query RebelsQuery {
  rebels {
    id
    name
  }
}

returns

{
  "rebels": {
    "id": "RmFjdGlvbjox",
    "name": "Alliance to Restore the Republic"
  }
}

So now we know the ID of the Rebels in our system. We can now refetch them:

query RebelsRefetchQuery {
  node(id: "RmFjdGlvbjox") {
    id
    ... on Faction {
      name
    }
  }
}

returns

{
  "node": {
    "id": "RmFjdGlvbjox",
    "name": "Alliance to Restore the Republic"
  }
}

If we do the same thing with the Empire, we'll find that it returns a different ID, and we can refetch it as well:

query EmpireQuery {
  empire {
    id
    name
  }
}

yields

{
  "empire": {
    "id": "RmFjdGlvbjoy",
    "name": "Galactic Empire"
  }
}

and

query EmpireRefetchQuery {
  node(id: "RmFjdGlvbjoy") {
    id
    ... on Faction {
      name
    }
  }
}

yields

{
  "node": {
    "id": "RmFjdGlvbjoy",
    "name": "Galactic Empire"
  }
}

The Node interface and node field assume globally unique IDs for this refetching. A system without globally unique IDs can usually synthesize them by combining the type with the type-specific ID, which is what was done in this example.

The IDs we got back were base64 strings. IDs are designed to be opaque (the only thing that should be passed to the id argument on node is the unaltered result of querying id on some object in the system), and base64ing a string is a useful convention in GraphQL to remind viewers that the string is an opaque identifier.

Complete details on how the server should behave are available in the GraphQL Object Identification spec.