Pluragraph

GraphQL API

Introduction

What is GraphQL

Learn more about GraphQL from the official documentation

GraphQL terminology

Fields

A field is a unit of data you can retrieve from an object. As the official GraphQL docs say: "The GraphQL query language is basically about selecting fields on objects."

Connection

Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API.

It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.

Edge

Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges field has a node field and a cursor field. Cursors are used for pagination.

Node

Node is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.

Inline Fragments

If you are querying a field that returns an interface or a union type, you will need to use inline fragments to access data on the underlying concrete type.

On the Pluragraph api this applies to the trackings. The following inline fragments are available:

  • serviceFacebookTracking
  • serviceFlickrTracking
  • serviceGooglePlusTracking
  • serviceInstagramTracking
  • serviceTwitterTracking
  • serviceYoutubeTracking

Endpoint

The endpoint remains constant no matter what operation you perform.


  https://pluragraph.de/api/graphql

All requests must be HTTP POST requests with application/json encoded bodies.

Authentication

GraphQL requests must be authenticated using an API Access Token. Pass the token in your GraphQL request using the Authorization HTTP header with a value Bearer token.


  curl --request POST \
  --url https://pluragraph.de/api/graphql \
  --header 'authorization: Bearer YOUR_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"{ user{ fullName } }","variables":{}}'

GraphQL explorer

To make it easier to test, explore and experiment with the API we’ve set up GraphiQL, an official open-source GraphQL project, which gives you a code editor with auto-complete and inline documentation.

To use the explorer you’ll first need a Pluragraph account. After you have logged in you should be able to explore the api.

Above the following query samples you may see a link that says "Run in Explorer." Click the link and you'll go to the Explorer window with the query sample already filled in.

Sample Query: User

The following is a basic GraphQL query that requests the name of the current user (the account attached to the API Access Token, i.e. you!)

Run in Explorer
 
{
  user{
    firstName
    lastName
  }
}
And the curl code for the same request

  curl --request POST \
  --url https://pluragraph.de/api/graphql \
  --header 'authorization: Bearer YOUR_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"{ user{ firstName lastName } }","variables":{}}'

Sample Query: Organisation

The following query requests an organisation with the given id. It also requests any ancestry for the organisation and the first profile in that organisation.

Run in Explorer
 
{
  organisation(id: "f0f0b741-aa0a-4dd3-a14e-e80d1a1e5155") {
    name
    ancestry {
      name
      id
      ancestry {
        name
        hasParent
      }
    }
    profilesCount
    profiles(first: 1) {
      edges {
        node {
          identifier
          isMasterProfile
          rankValueAttributeName
        }
      }
    }
  }
}

Sample Query: Category

The following query requests a category, with the given id, listing all the organisations in this category.

Run in Explorer
 
{
  category(id: "f909afa7-3d21-4838-994d-366db9506fac") {
    name
    isRoot
    ancestry {
      name
      id
      isRoot
      ancestryRoot{
        name
      }
    }
    organisationsInCategory: organisationCategoriesCount
    organisations{
      edges{
        node{
          name
        }
      }
    }
  }
}

Sample Query: Trackings

To get the tracking data for a certain Facebook profile you have to provide the profile_id and use the "...on serviceFacebookTracking" fragment.

Run in Explorer
 
{
  trackings(profile_id: "582ec9be-6e79-41ca-bdf1-b037f75e0a2f"){
    ...on serviceFacebookTracking{
      date
      fanCount
      fanCountWeekAgo
      fanCountWeekGrowth
    }
  }
}

Sample Query: Watchlist

Are you only interested in a few Organisations? Then watchlists are a great way to get the information on those profiles.

The following query fetches the watchlist and the connected profiles. For each profile it also fetches the last 7 trackings. Using fragments you specify which information to get for the different profile types.

Watchlist are always scoped to the current user.

Run in Explorer
 
{
  watchlist(id: "91973214-1d56-49e2-a125-3cd697de1e5b") {
    id
    name
    profiles{
      edges{
        node{
          identifier
          type
          trackings(first: 7){
            edges{
              node{
                ...on serviceFacebookTracking{
                  fanCount
                  date
                }
                ...on serviceTwitterTracking{
                  followerCount
                  date
                }
                ...on serviceFlickrTracking{
                  mediaCount
                  date
                }
                ...on serviceGooglePlusTracking{
                  plusOneCount
                  date
                }
              }
            }
          }
        }
      }
    }
  }
}