GraphQL

The Appfarm platform has built-in support for querying your data through GraphQL. GraphQL can be used as a developer tool to view and modify data in your solution, as well as a method for exposing your data model to external parties for integration.

One of the powerful features available with GraphQL is the ability for the client user to construct a single query that returns only the data they need and nothing more. You do not need to define an API in advance, but simply select which object classes and data operations should be exposed.

What is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. - graphql.org To learn more about GraphQL, check out the external resource Introduction to GraphQL.

Enable GraphQL

GraphQL support is turned off by default and needs to be enabled at both the environment and object class level. The GraphiQL IDE can also be activated for testing queries and viewing data.

Follow these steps to enable GraphQL in your solution:

1. Under Environments, within each environment that you want to enable GraphQL:

   • Select Enable GraphQL.

   • Select Enable GraphQL Explorer if you also want to enable the GraphiQL IDE.

2. Under Global Data Model, select an object class that you want to expose via GraphQL. In the object class properties:

   • Select Enable GraphQL.

   • Edit the Endpoint Name if you wish. This is the name of the GraphQL object type.

   • Select the operations you wish to enable:

     • Enable Read

     • Enable Aggregate

     • Enable Create

     • Enable Update

     • Enable Delete

Repeat step 2 as required for other object classes.

Remember to deploy

Changes to object class properties, including GraphQL access, must be deployed to be represented in other environments.

GraphiQL IDE

Note: To access the GraphQL Explorer in a given environment, you must be logged in to the Appfarm client in that environment.

GraphiQL is a handy tool for working with your data during development and for verifying what data is accessible through GraphQL. You can write queries on the left-hand side and the response is displayed on the right-hand side. You can quickly check what object classes and operators you have exposed by clicking Docs in the top right-hand corner and exploring the structure.

GraphiQL IDE

To access the GraphiQL IDE you must have first enabled GraphQL Explorer. Then, you can either:

• Visit the URL https://SOLUTION-HOSTNAME/api/graphql/. Note that the solution hostname is environment specific.

• Under Global Data Model click Explore API and click the relevant environment.

The URL path of the GraphiQL IDE also serves as the API endpoint for that environment.

When using GraphiQL you are logged in with your client user. Your data access permissions in GraphiQL are granted from your role(s).

For more information on how to use GraphiQL, see Queries and Mutations.

Integration

Third-parties can integrate with your solution via GraphQL. The GraphQL API sits underneath the Appfarm Platform's security layer so only authorized users will be able to execute queries.

For a third-party to integrate with your GraphQL API, you will need to configure their access.

1. Create a role and assign the necessary environment and object class permissions.

2. Create a service account and assign the newly created role.

3. Create an API key for the service account. Select the GraphQL Access checkbox. Store the API key in a secure location as it is not possible to view it again.

4. Provide the GraphQL endpoint (https://SOLUTION-HOSTNAME/api/graphql/) and API key to the third-party.

To authenticate, they must either:

• Add Bearer API-KEY as an Authorization header in the request.

• Add token=API-KEY as a URL query parameter

The third-party can then run GraphQL queries and mutations towards your GraphQL endpoint. You may use either a GET request or a POST request.

• GET request: You must add the GraphQL query or mutation as a Query Parameter with query as key and your query/mutation as value

• POST request: The body must be a JSON object with query as a key and your query/mutation as value, e.g. { "query": "{project(filter:{projectNumber:{eq:123456}})}"}

The response is formatted as JSON.

Please check out the example on how to run GraphQL queries from an Appfarm App in this section. The example is also relevant for third-parties wanting to integrate towards Appfarm's GraphQL endpoints.