Using GraphQL with Oracle's MERN Stack

This post will discuss using GraphQL with the Oracle's MERN Stack. This is Oracle's full stack for Web and Mobile development based on Parse Platform. It will discuss using the Parse Dashboard GraphQL Playground to prototype queries and run through some basic GraphQL concepts. The next post will discuss how to use GraphQL from the GameScore Mobile Application Demo which is written in Flutter

Why GraphQL

GraphQL offers several advantages that might make you want to use it in your web and mobile development projects:

1. Efficient Data Fetching: GraphQL allows clients to request only the specific data they need, avoiding over-fetching or under-fetching of data. This reduces the amount of data transferred over the network, improving performance.
2. Single Endpoint: GraphQL typically uses a single endpoint for all data queries and mutations, simplifying the API structure compared to REST, which often requires multiple endpoints for different resources.
3. Strongly Typed: GraphQL schemas are strongly typed, which means you can define the data structure, types, and relationships in a clear and organized manner. This helps catch errors early in the development process.
4. Real-time Data: GraphQL can support real-time data updates using subscriptions, allowing clients to receive updates when data changes on the server.
5. Versioning: GraphQL eliminates the need for versioning APIs, as clients can request only the fields they need, and adding new fields or types to the schema doesn't affect existing clients.
6. Frontend Flexibility: GraphQL empowers frontend developers to request the data they need for a particular view or component without relying on backend changes. This can lead to more independent and efficient frontend development.
7. Reduce Overhead: GraphQL reduces the need for multiple round-trip requests to fetch related data, as you can define complex queries that retrieve all necessary data in one request.
8. Tooling: GraphQL has a rich ecosystem of tools, libraries, and development aids, making it easier to work with and explore your API.
9. Client-Specific APIs: With GraphQL, you can create APIs tailored to the specific needs of your clients, whether they are web applications, mobile apps, or other services.
10. Documentation: GraphQL APIs often come with self-documenting capabilities, making it easier for developers to understand and work with the API without separate documentation.

Overall, GraphQL offers greater flexibility and efficiency compared to traditional REST APIs, making it a compelling choice for many modern web and mobile applications, particularly those with complex data requirements or evolving frontend needs.

GraphQL Playground

When installing the Mobile Application Development Stack to the Oracle Cloud, the Parse Dashboard is configured, booted and ready to use OOTB. The Parse Dashboard provides a slew of management and configuration capabilities for Parse Server. It also provides code Playgrounds, 3 specifically. They are REST, JavaScript and GraphQL.

The GraphQL Playground is divided into 3 columns

• Documentation on the left
• Code Editor in the center
• Output on the right

The query above gets all the GameScore documents from the GameScore collection. The query supports pagination and uses edges and nodes. In GraphQL, an "edge" is a concept used within connection-based queries to represent a single item in a list or collection of data. It is typically used in combination with "nodes" to structure the data in a standardized way, especially when retrieving paginated data. Here's how it works:

1. Node: The "node" is an object that represents a single item in the list or collection. It contains the actual data for that item.
2. Edge: The "edge" is an object that acts as a container for the "node" and can include additional information about the item, such as a cursor (a unique identifier for that item) or any other metadata related to the item.
3. Connection: The "connection" is an object that contains the list of "edges." It provides information about the overall collection, such as the total count of items, and offers a way to paginate through the data. This structure is commonly used in GraphQL when you want to retrieve a list of items with additional information about each item, especially when dealing with large datasets where pagination is necessary.

In this example, we're retrieving all the GameScore documents, and for each GameScore, we're getting the "id", "playerName", "score" and "cheatmode within the "node" object. The "cursor" within each "edge" helps with pagination, and "totalCount" in the "connection" object gives the total count of nodes in the collection.

The data returned has 3 nodes and edges with the edges containing the relative cursor position. There is pageInfo information prior to the edges. In GraphQL, "PageInfo" is an object type used to provide information about pagination in connection-based queries. Connection-based queries are often used to retrieve lists of items, and PageInfo helps in managing pagination by offering details about the current page of data and the ability to navigate through the dataset. PageInfo typically includes the following fields:

1. "hasNextPage": A Boolean field that indicates whether there are more items available in the next page of data. If "hasNextPage" is true, it means there are more items to fetch.
2. "hasPreviousPage": Similar to "hasNextPage," this field is a Boolean that indicates whether there are items in the previous page of data. If "hasPreviousPage" is true, it means you can navigate backward.
3. "startCursor": This field provides a cursor (a unique identifier) for the first item in the current page of data. It helps in defining where the current page starts.
4. "endCursor": This field provides a cursor for the last item in the current page of data. It helps in defining where the current page ends.

The PageInfo object is often included as part of a connection-based query response to provide clients with essential information for paginating through a dataset. This allows developers to implement efficient and user-friendly pagination in GraphQL APIs.

Creating a New Collection

The following mutation creates a new Course schema.

This mutation created a schema entry for the Course collection

But what is a mutation?

In GraphQL, a mutation is a type of operation that is used to modify or change data on the server. While queries in GraphQL are used to retrieve data, mutations are used when you want to create, update, or delete data. Mutations are similar in structure to queries but are designed to make modifications to the data rather than fetching it. Here are some key points about GraphQL mutations:

1. Keyword: Mutations in GraphQL are defined using the "mutation" keyword followed by the name of the mutation and any input arguments it requires. In this example, the mutation name is createClass.
2. Input Arguments: Mutations often require input arguments, which specify the data that should be modified. These arguments are defined in the mutation's schema. The "clientMutationId" is a field that can be included in a mutation request. It is an optional piece of data that can uniquely identify a specific mutation request.
3. Return Type: Like queries, mutations specify what data should be returned after the mutation is performed. This allows the client to get confirmation or details about the changes made.
4. Side Effects: Mutations can have side effects on the server, such as creating a new record in a database, updating an existing record, or deleting data.

Dynamic Doc

Once the Course class is created, new queries and mutations are also created and immediately available in the documentation. But first, refetch the GraphQL schema from Parse Server by clicking the button on the lower left

Drill down in Query to view the new Course Query APIs

And drill down in Mutation to see the new Course Mutation APIs

Dynamic API Doc, pretty impressive imho

Create Course Document

Let's use one of these new mutations to create a Course document.

Successful creation of a Course document. You can see the full document that was created in the return pane. It has the clientMutationId for request correlation and the all the fields that make up a course document instance including unique ID, timestamps and Access Control Lists.

Summary

I hope this overview of GraphQL was helpful and encourages you to take a look at the new Mobile and Web Development Stack deployed to the Oracle cloud. Everything I demonstrated here can be done OOTB from an Oracle's MERN Stack. Look for the next post which will cover using GraphQL from within a Flutter Mobile Application.