GRAPHQL API

Introduction

GraphQL is a query language for API communication that allows you to request exactly the data you need — simply and efficiently. This is why we chose to make our new API GraphQL-based. It lets you access data stored in a Planforge repository via web service calls, providing your data in the JSON format. If you have never worked with GraphQL before, we recommend reading the excellent official introduction.

For all demonstration purposes, let's assume your Planforge instance is running on a local server on port 8080 over HTTP, the WAR package is called planforge.war and your Planforge instance is therefore accessible via http://localhost:8080/planforge. The API endpoint is then:

http://localhost:8080/planforge/api/v3/

https://europe.planforge.io/api/v3/

GraphiQL playground

When navigating to this endpoint in a browser, you are presented with an interactive online playground powered by GraphiQL, in which you can try out all available queries and mutations. We recommend you try the examples provided in this introduction right away in this browser based GraphQL IDE. However, before being able to successfully retrieve data from your Planforge Server or cloud site, you need to authenticate yourself.

Authentication

Planforge uses OAuth 2.0 bearer tokens for authentication of external systems. You can either create an access token for your account within the Planforge web interface, or use the provided OAuth 2.0 authentication flow to automatically have your access token created automatically.

Automatically creating an access token

To automize the creation of your access token and have it automatically entered in GraphiQL, Planforge also supports an OAuth 2.0 authentication flow. Head over to http://localhost:8080/planforge/api/v3/login and login with your username and password On the following screen, grant the application access to your Planforge account. Once successfully logged in, you will be redirected to the GraphiQL IDE, with your access token supplied automatically.

Manually creating an access token

To manually create a bearer token, head over to the Administration area (wrench icon in the top right corner) inside your Planforge installation, select Users on the left hand side, and open the properties of the user you wish to authenticate as, either by double-clicking the user in the list or selecting the user and clicking the Properties button in the menu bar. In the user properties dialog, head over to the Tokens tab and click on New Token to open the dialog for creating an API token. In that dialog, select API as the external app, and optionally assign a name to the token.

Using your access token in GraphiQL

To use your access token in GraphiQL, you need to enter the following object in the HTTP HEADERS tab in the lower left of the page. If you used the OAuth 2.0 authentication flow as described above, you will find this information prefilled for you.

{
  "Authorization": "Bearer your-token-here"
}

Once entered, you are able to send queries and mutations to the GraphQL endpoint of your Planforge cloud or server installation. Of course, you can only access or alter data that your account has permissions for.

Using your access token outside of GraphiQL

Of course, the generated tokens can be used to integrate any external system with your Planforge instance. To do so, every HTTP request that gets dispatched must include the token in a header field Authorization with a value of Bearer <your-token-here>, as the following example shows.

{
  "Authorization": "Bearer your-token-here"
}

Working with the API

Once you have obtained your API token, almost any business objects can be fetched, modified and deleted. In GraphQL, all calls should use the POST method to allow the query to reside in the body of the request. For queries, a GET request may also be used by appending the query string to the call endpoint, but we discourage doing so.

GrapqhQL allows you to request exactly the data you need. Instead of requesting data from different endpoints, all requests are directed towards the root endpoint, in our case http://localhost:8080/planforge/api/v3. The structure of the request query or mutation dictates the structure of the response, as can be seen in the following examples. One thing to keep in mind is that the actual content will always be wrapped in the data property of the response JSON.

Fetching Data

query PlannedEffortOfProjects {
  projects {
    name
    plan {
      baselineVersion {
        rootActivityVersion {
          effort {
            planned {
              inHours
            }
          }
        }
      }
    }
  }
}

{
  "data": {
    "projects": [
      {
        "name": "Database Cluster Migration",
        "plan": {
          "baselineVersion": {
            "rootActivityVersion": {
              "effort": {
                "planned": {
                  "inHours": 400
                }
              }
            }
          }
        }
      },
      {
        "name": "Jira Integration Demo",
        "plan": {
          "baselineVersion": {
            "rootActivityVersion": {
              "effort": {
                "planned": {
                  "inHours": 320
                }
              }
            }
          }
        }
      },
      ...
    ]
  }
}

Altering Data

In GraphQL, mutations are used to alter data on your backend. The result of a mutation also allows subselection of properties, again giving you the opportunity to only retrieve a customized set of properties. With mutations, it can be helpful to query the properties that were changed during execution. In the sample mutation below, we move a resource node into a different pool. In terms of result selection, we select the resources pool (its name and id, specifically), and see that the resource has indeed been moved. Again, all content is wrapped in the data property.

mutation moveResource {
  moveResourceNode(sourceId: 60162057, targetId: 60162051) {
    pool {
      name
      id
    }
  }
}

{
  "data": {
    "moveResourceNode": {
      "pool": {
        "name": "Organization/IT",
        "id": "60162051"
      }
    }
  }
}

Error handling

GraphQL allows for partial errors in API calls. Should one path of your request fail, other paths will stay unaffected and will still return the correct data where possible. In case of an error, the response will have an errors property next to its data property that will give you more detail about the error you ran into.

Planforge GraphQL Schema

We strongly encourage you to use GraphiQL (you can reach it at the endpoint api/v3) on your Planforge installation to explore all available queries, mutations and types in the schema. If you currently have no access to a Planforge instance, our schema can also be viewed here, but you won't be able to try out queries or mutations.