ONEPOINT GraphQL API

ONEPOINT Projects is always up to date when it comes to using the latest technology in its products. We continue this by urging our customers to use the new GraphQL API to integrate external systems with ONEPOINT Projects.

The following short tutorial gives an overview of general setup, authentication and will help you overcome common pitfalls that might occur when working with the GraphQL API.

We strongly recommend using GraphQL API to integrate ONEPOINT Projects with other systems. We do still offer a REST API with JSON and XML endpoints for the foreseeable future.

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 ONEPOINT Projects 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 ONEPOINT Projects instance is running on a local server on port 8080 over HTTP, the WAR package is called onepoint.war and your ONEPOINT Projects instance is therefore accessible via http://localhost:8080/onepoint. The API endpoint is then:

http://localhost:8080/onepoint/api/v3/
Cloud example:
https://europe.onepoint-projects.com/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 ONEPOINT Server or cloud site, you need to authenticate yourself.

Authentication

ONEPOINT uses OAuth 2.0 bearer tokens for authentication of external systems. You can either create an access token for your account within the ONEPOINT 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, ONEPOINT also supports an OAuth 2.0 authentication flow. Head over to http://localhost:8080/onepoint/api/v3/login and login with your username and password On the following screen, grant the application access to your ONEPOINT 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 ONEPOINT Projects 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.

Make sure to close the user properties dialog before trying out your token, to ensure that it gets saved to the database!

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 ONEPOINT 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 ONEPOINT 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/onepoint/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

Sample query
query PlannedEffortOfProjects {
  projects {
    name
    plan {
      baselineVersion {
        rootActivityVersion {
          effort {
            planned {
              inHours
            }
          }
        }
      }
    }
  }
}
Sample Response
{
  "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.

Sample mutation
mutation moveResource {
  moveResourceNode(sourceId: 60162057, targetId: 60162051) {
    pool {
      name
      id
    }
  }
}
Sample Response
{
  "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.

ONEPOINT GraphQL Schema

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

Ready for the next step?

ONEPOINT Projects is the first 100% web-based, fully-integrated project and portfolio management solution that does not force you to compromise between usability and deploying a "real" PPM solution. Interested?

Watch tutorial videos Get free trial