GraphQL Overview:
ANZ Cash Management Central (ACMC) leverages the power of GraphQL for its API interactions, providing developers with an efficient and flexible way to access, manipulate, and retrieve data. Unlike traditional REST APIs, GraphQL allows developers to specify exactly what data is needed, avoiding the inefficiencies of over-fetching or under-fetching data. This approach ensures optimised API performance and provides granular control over how data is requested and manipulated.
Key Features of GraphQL in ACMC:
-
Efficient Data Retrieval: Developers can query precisely the data they require, even from deeply nested structures, in a single request. This leads to a significant reduction in the number of API calls and overall data payload.
-
Customisable Queries: The flexible querying capabilities of GraphQL allow for tailored data retrieval based on the specific requirements of the operation. Whether you are reading, writing, or updating data, queries can be constructed to only return relevant fields.
-
Reduced Overhead: With the ability to combine multiple nested queries into a single call, GraphQL helps reduce network overhead and latency, streamlining operations.
-
Scalable Performance: GraphQL supports advanced operations such as pagination, filtering, and sorting, which are essential when dealing with large datasets.
Before You Begin:
If you are new to GraphQL, we encourage you to familiarise yourself with the core concepts of GraphQL before diving into the ACMC API. GraphQL offers a unique approach to querying APIs, and understanding its fundamentals will help you get the most out of ACMC’s API capabilities. Visit the official GraphQL documentation at graphql.org
to explore tutorials and resources that will provide you with a solid foundation.
Core GraphQL Operations in ACMC:
-
Queries: Queries are the core operations for retrieving data in GraphQL. At the root level, the
Query
type defines the entry point for data access. This can include retrieving basic scalar values or more complex objects, supporting flexible data fetching at various levels of the data hierarchy. -
Mutations: Mutations handle data modification in ACMC. Whether creating new entities, updating existing records, or deleting data, mutations provide a structured way to alter the state of the system. Mutations also return data, allowing you to verify changes after an operation has been completed.
GraphQL Types:
-
Object Types: GraphQL schemas in ACMC are built around object types, which represent the primary entities in the system, such as
User
,Account
, orTransaction
. Each object type contains fields that can be queried, making it easy to retrieve related data through a single API request. -
Enum Types: Enum types define a set of predetermined values for fields. For instance, an enum like
AccountStatus
could have values such asACTIVE
orCLOSED
. These types ensure data consistency and prevent invalid inputs. -
Scalar Types: Basic types such as
Int
,Float
,String
,Boolean
, andID
form the foundation of the GraphQL type system. Scalar types represent simple values and are used throughout queries and mutations. -
Input Types: Input types enable structured data to be passed into mutations, allowing for complex objects to be created or updated with ease. This is particularly useful when dealing with detailed entities such as accounts or transactions that require multiple fields.
-
Interface Types: Interfaces in GraphQL allow for different object types to share common fields. This is particularly useful in ACMC, where multiple types might share fields like
name
oraccountNumber
but still represent distinct entities.
Validation and Execution in GraphQL:
GraphQL follows a two-step process for handling queries and mutations: Validation and Execution.
-
Validation: When a query is sent to the GraphQL API, it first undergoes a validation phase. During this step, the query is checked against the GraphQL schema to ensure that it is syntactically correct and adheres to the schema’s rules. This process includes validating the types, arguments, and fields requested. If any issues are detected—such as requesting non-existent fields or providing incorrect arguments—the query will be rejected, and an error message will be returned.
-
Execution: Once the query passes validation, it proceeds to the execution phase. In this phase, the GraphQL server resolves the query by fetching the requested data. The execution process follows the structure defined in the query, executing field by field, and resolving any nested fields as necessary. The final response is then compiled and returned to the client in the form of a JSON object, containing only the requested data.
The combination of validation and execution ensures that all queries are robust and that only valid requests reach the execution phase, reducing the risk of errors and optimizing the data retrieval process.