GraphQL

he 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. Queries can be entered in the middle section and the response is displayed on the right-hand side. The Docs can be opened by clicking the book icon in the top left corner to show what object classes and operators are available. New tabs can be added by clicking the plus icon on top of the code editor.

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 as your client user. Your data access permissions are granted by your role(s).

GraphiQL Explorer

Queries and Mutations can be built using the GraphiQL Explorer. As shown in the image below, the Explorer can be opened by clicking the bottom icon in the left pane. The Explorer lists all available endpoints, properties, and operators. Select what to query from the list on the left-hand side, and the IDE will build the query.

GraphiQL Explorer

Integration

Third parties can integrate with your solution via GraphQL. The GraphQL API is located underneath the Appfarm Platform's security layer, so only authorized users can 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. Use GET requests for queries and POST requests for mutations.

• GET request: You must add the GraphQL query as a Query Parameter with query as key and your query as value
• POST request: The body must be a JSON object with query as a key and your 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.