GraphQL IDs and nodes

The Elium API follows the Relay server specification for identifying objects. One idea from it appears in almost every guide: the node.

Two identifiers: slug and GraphQL ID

Most objects in Elium have two identifiers.

• The slug is the number you see in the address bar: 123 in https://your-platform-name.elium.com/tile/view/123/. It is unique within one type of object only. A user and a story can both have the slug 123, because they are different types.
• The GraphQL ID is a string the server generates, such as U3Rvcnk6MTIz. It is unique across every object of every type. Mutations take GraphQL IDs, not slugs, with rare exceptions such as storyUndelete.

Queries such as story(slug:) and space(slug:) accept a slug and return the object with its id field, which is the GraphQL ID. That is the usual way to get the ID you need for a mutation.

The node query

Every object with a GraphQL ID implements the Node interface, which has one field, id. The node query returns any of these objects from its ID.

Because node can return any type, you must say which type and fields you expect with an inline fragment, ... on Story in this example:

query {
  node(id: "U3Rvcnk6MTIz") {
    ... on Story {
      id
      version {
        title
      }
      user {
        name
      }
    }
  }
}

If the ID belongs to another type, the fragment does not match and the result contains none of those fields. GraphQL interfaces explains the mechanism.

Get a story shows the two ways of reading the same story, by slug and by node, side by side.