Design uplift seris- Part 4 BFF design ( in progress)

 

Part 1 BFF design article explains  what are the main advantages of Graphql for implementing BFF and important scenarios where Graphql can be used. Other aspects like security and common anti design patterns and  how to over come them. Articles don't discuss  about in-depth explanation of how to design schema ,query , types and mutations  .

  Right now selecting a particular graphql server mostly depend on the programming language used  for application development., there are few vendors having solution and can be adopted without much comparison              of   alternative deigns. The choice  mostly   linked to the programming language being used             in     application/ product. But this will change as BFF is very much part of best design patterns    now             like api layer design or repository pattern , slowly BFF layer become part of most of new design / architecture diagrams . which indicates that better tooling and handling complex scenarios needs better choice interms of tooling along with choice of Graphql server. So the article will explain total end to end system design not just setting up Graphql server. Newly developed solution for graphql server like Yogagraphql already has more than 40k downloads. It shows that there will be more design alternatives going forward.

          If we look at some of the security  risks  discussed  in Book                "Black Hat GraphQL"  it also give                examples how                   graphql servers by few vendors providing additional security.             So there are many parameters along with setting up graphql             server. Security, schema generation, managing sub graph     -            and moving towards federation graphql .  All these parameters         helps to     design better grapql eco system. I am using apollo             client  which can cache client side data if the query is not                 changed. These     are few      features by these vendors some             times can  influence  whole     design.

 Part 2 in this article we can look at the available design options and the suitable use case will be discussed. It is important to understand in depth capabilities of the existing frameworks which can help to quickly bring Graphql server and Graphql client and can also add lot of features like security , build , logging  , scalability and other components as plug and play ,  as these  frameworks  are designed with lot of add on components and easy to integrate using API  .

Design Objectives

Let us consider few important use cases where Graphql being used extensively. One of the design discussion is about all the objects in graphql are connected like graph and also query represents closely with the data design.

 

There are many articles  discussing above  inherent feature of Graphql and advantages and disadvantages. As one article explains it as schema is graph and queries results in tree only. The articles also extending advantage of using graphql for graph based data bases. It also explains with good examples and how to validate and maintain data quality so that it works with graphql better way.

One way to look at designing Graphql server with Neo4j or similar frameworks are  more close to data driven design . There could be many variations to above.

There few advanced graphql servers they can help to expose DTO objects as graphql end points.  Hasura is one such grapqhql implementation. Similar thinking and design but Hasura will talk more about DTO object instead of data base type.

Let us look at AWS  design for Graphql server  with the  APP Sync based design.

 

As explained by AWS  the three subgraphs are composed into the Fusion gateway which is ran as a Fargate service behind an Application Load Balancer.

Above system developed by aws brings in the following advantages as it was shipping graphql server with lot of features already available and which can be extended based on application design. Here are few advantages of using above

Real-time data synchronization using subscriptions. Integration with AWS services like DynamoDB, Lambda, and S3.Simplified authorization with Amazon Cognito, API keys, and IAM.

Api  load balancing  and  security capability of IAM and also can make use of AWS components quickly.  Dev focus could be   implementing  schema , types and query files. This kind of design approach where lot of components can be plugged in can reduce development time . we can discuss more about  some of the major features which can be more attractive in selecting the design  when we try to compare different designs available for a real time example. 

Hot Chocolate: Hot Chocolate is a GraphQL platform for that can help you build a GraphQL layer over your existing and new infrastructure.

More precisely Hot Chocolate is an open-source GraphQL server for the Microsoft .NET platform that is compliant with the newest GraphQL October 2021 spec + Drafts, which makes Hot Chocolate compatible to all GraphQL compliant clients like Strawberry Shake, Relay, Apollo Client, and various other GraphQL clients and tools.  As it is more Microsoft platform based design and can work closely with Microsoft infrastructure.

Express Graph ql, Appollo Graphql server and server other   popular frameworks available to implement grpahql server. We can dive deep when we try to design couple of  real time example after discussing some more important design patterns and frameworks.

Design Patterns and Use cases

Let us consider scenario where an monolithic application having MVC pattern which was adopted by many legacy systems. When it is required to redesign above systems based on latest micro service based cloud enabled applications , new patterns like BFF, serverless and other  technologies are recommended for new application design. 

Use case 1: Refracting legacy Application:

In a simple design if all controller end points are mapped to an graphql end point and Client which is view  decoupled form MVC pattern it is one way to break monolithic application. This one is most adopted  approach in industry  I can see this approach is  best use case in industry for introducing BFF layer and graphql.

                   Let us  look at complete set of components and process                        involved in adopting Graphql

Design Graphql Server which also involve designing schema, query, types     and  resolvers to fetch data.

Designing some cache components  and optimizing data fetching using          pagination  and error handling, Client side design to interact with grapqhql  server.

Next will be API management related aspects like versioning and load    balancing.

Tooling : Here comes the major design decision as lot of vendors gives readily available schema generators, Visual designers for schemas ,query and  types  design,  testing frameworks  and every thing required to set up Graphql server  and to perform above 4 step with attractive  low code no code kind of  approach. So all  pending work could be   just hooking resolvers with data end points.    

The above refactoring and redesign exercise  can be extended to address lot of design considerations like separation of concerns  or abstracting   data 

We can discuss in depth scenarios for above design transition form MVC to Graphql server and then we can consider different platforms available which can be best fit for the above refracturing or tech refresh exercise.

Use case 2 API Aggregation : Aggregating multiple apis internal and./or external and abstracting api details from Clients.

Use case 3 BFF Design: Building more modular patterns in application design using BFF.

User case 4 Using Graphql along with Micro srvices : Graph QL for managing microservices and service mesh.

Here is one example of robust architecture for use case 4 using applo federation and microservices with an Api gateway 

Ref: https://talashlogs.blob.core.windows.net/talash-drive/leveraging-graphql-for-next-generation-api-platforms.pdf

Important design aspects for this reference architecture are : 

Appollo provides lot of ready to use components along with Graphql server. As discussed above it is like a platform which can give lot of other components to maintain Graphql infrastructure and quickly build application. As shown in this diagram Apollo provides a GraphQL developer platform (GraphOS), which includes developer tooling, a schema registry, and a supergraph CI/CD pipeline and high-performance supergraph runtime.

Even Appollo clients provided can manage cache control at client side . Cache  management is bit tricky and needs  more components to maintain server cache and client cache which we can discuss later.

Other components in diagram are Kong API gateway . This could be any other API manager  . Important point here is Micro services needs service mesh to communicate and then they are connected to Graphql server. Bit of load balancing and security achieved with these API gateways embedded in the design. 

Security is often handled with a defense-in-depth or zero-trust approach, where each layer of the stack provides security controls for authentication, authorization, and blocking

malicious requests. Client-side traffic shaping with rate limits, timeouts, and compression can be implemented in the API gateway or supergraph layer, and subgraph traffic shaping

(including deduplication) can be implemented at the supergraph layer. Observability via Open Telemetry is supported across the stack to provide complete end-to-end visibility into each

request via distributed tracing along with metrics and logs. 

 

(Apollo Router).

Here is another way to classify above use cases.- 

 

Pattern	Advantages	Challenges	Best Use Cases
Client-Based GraphQL	Easy to implement, cost-effective	Performance bottlenecks, limited scalability	Prototyping, small-scale applications
GraphQL with BFF	Optimized for clients, better performance	Increased effort, higher complexity	Applications with diverse client needs
Monolithic GraphQL	Centralized management, consistent API	Single point of failure, scaling issues	Medium-sized applications, unified schema
GraphQL Federation	Scalable, modular, team autonomy	Increased complexity, higher learning curve	Large-scale, distributed systems

Best practices

What are the key principles of schema design in GraphQL?

Designing a GraphQL schema with flexibility and scalability in mind involves several key principles that ensure the schema can grow and adapt to changing requirements while maintaining performance and usability.

• Unified Schema: A GraphQL schema defines a collection of types and their relationships in a unified manner. This allows client developers to request specific subsets of data with optimized queries, enhancing flexibility.
• Implementation-Agnostic: The schema is not responsible for defining data sources or storage methods, making it adaptable to various backend implementations without requiring changes to the schema itself.
• Field Nullability: By default, fields can return null, but non-nullable fields can be specified using an exclamation mark (!). This provides control over data integrity and error handling, contributing to robust and scalable schema design.
• Query-Driven Design: The schema should be designed based on client needs rather than backend data structures. This approach ensures that the schema evolves with client requirements, supporting flexibility and scalability.
• Version Control and Change Management: Maintaining the schema in version control allows tracking of changes over time. Most additive changes are backward compatible, but careful management of breaking changes is essential for scalability.
• Use of Descriptions: Incorporating Markdown-enabled documentation strings (descriptions) in the schema helps developers understand and use the schema effectively, promoting a flexible development environment.
• Naming Conventions: Consistent naming conventions, such as camelCase for fields and PascalCase for types, ensure clarity and ease of use across different client implementations, aiding in scalability

Tools and devops 

References:

Apollo graphql federation:

 https://talashlogs.blob.core.windows.net/talash-drive/Apollo-graphql-at-enterprise-scale-final.pdf

Security and pen test

https://talashlogs.blob.core.windows.net/talash-drive/Black+Hat+GraphQL_bibis.ir.pdf

PentestingEverything/API Pentesting/GraphQL at main · m14r41/PentestingEverything

Design patterns

https://drive.google.com/viewerng/viewer?url=https://talashlogs.blob.core.windows.net/talash-drive/API+Composition+Pattern+with+GraphQL.pdf

Naming and best practices and schema design

GraphQL: Standards and Best Practices | by Andrii Andriiets | Medium

GraphQL Best Practices for Efficient APIs

Modernize your API Stack with GraphQL and Azure API Management

 

In this article from our series from INTEGRATE 2022, Let's take a deep dive into the session on how to modernize your API stack with GraphQL using Azure API Management, as presented by Elizabeth Barnitt, a Program Manager in Microsoft for API Management.

Elizabeth started her session with a bunch of product updates, including some features available in Public Preview.

• Authorizations: Managed Token Store and Token Mapping for OAuth2-Secured backends
• Private Link Integration: Simple to set up secure inbound connectivity to API Gateways available in all-tier except consumption one.
• Managed Certificate Support: Easily and quickly secure custom domains with free certificates automatically provisioned and renewed by API Management
• Synthetic GraphQL APIs: Easily create a GraphQL API based on your existing HTTP (SOPA or REST) APIs

The following features are generally available with Azure API Management,

• SOAP and XML request and response validation
• Validate Content Policy now support SOAP and XML-based Payload
• Schemas can now define as additional, service-level resources
• Event Grid Integration
• Subscribe to events from API Management in Event Grid to Automate workflows and process
• Self-Hosted Gateway V2
• Unified codebase, support for open Telemetry, new configuration endpoint
• WebSocket APIs
• Publish and mediate existing WebSocket APIs in API Management
• Developer Portal
• Inject custom HTML code into Managed Portal with the new widget
• Improved OpenAPI support in API reference pages and revised code samples
• Policy Fragments
• Define complex policies once and re-use them anywhere
• Power Platform Integration
• Export APIs as custom connectors for use in Power Apps and Automated Flows
• GraphQL APIs
• Publish and mediate existing GraphQL APIs in API Management

Why GraphQL?

REST APIs have been with us for many years now. In that time, our expectations of client applications have grown. We expect client applications to run on mobile devices with low bandwidth, yet still, be responsive. Unfortunately, REST APIs restrict us in three basic ways:

• It takes too many requests to fulfil the data needs for a single page.
• The REST API returns too much data for the page being rendered.
• The client application needs to poll to get new information.

Elizabeth showed a sample scenario with a Microsoft Store Page, which seemed relatively simple, but when analysed further, you realize you need to make so many REST calls to load this page. This is a major problem for all modern-day applications.

There have been various attempts to solve these issues, and the current favourite is GraphQL. GraphQL is a protocol specification that explicitly solves these issues. The client application can specify the data they need to render a page in a query document that is sent as a single request to the GraphQL service. A client application can also subscribe to changes in the data through a real-time WebSocket connection, allowing notifications to happen in a timely manner.

What is GraphQL?

• A query language for your API
• GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.
• A single call to a single endpoint
• 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.
• Helps to optimize the network bandwidth and reduces the number of calls to different API endpoints for different information
• Authorization
• Extremely secure, Instead of endpoint level authorization you can authorize at field level

Going back to the same example, but now with GraphQL, you can see that you are just running a single query to a single endpoint, and still get all of the data that’s needed to render the page.

Why do developers love GraphQL?

• Introspection
• This allows developers to discover the resources available to them in the GraphQL Schema. Developers can explore the schema, they can learn about different fields, queries and types.

This makes it easy for developers to onboard, explore and build on top of the existing queries that they are using.

• Auto Backward Compatibility
• The front end will not be broken when API gets updated. Rather than changing the endpoint itself and breaking the existing calls, it is much more focused on not making breaking changes by not changing the existing queries but rather adding new required queries.
• Client Generation
• Helps to send test queries via clients like Graphical or Insomnia.
• Self-Documenting
• All the queries, subscriptions, and types are automatically documented in the GraphQL Schema and when you generate a client this can be explored by developers.
• Real-time updates
• It does support real-time updates, for example whenever query results change server can return new results to the client

How do I implement GraphQL?

Elizabeth also touched upon how can you get started with implementing GraphQL.

• GraphQL Server
• Create a GraphQL Server using a tool like Apollo Server and create your schema and resources.
• Combine REST endpoints
• Aggregate multiple REST endpoints to Single Endpoint, by creating GraphQL Schema and mapping those endpoints' responses to GraphQL Schema resources so that data get served.
• GraphQL Server + Augmentation
• This is the combination of the first two options, relying on the existing GraphQL Server and extending the information from another REST point by attaching them to GraphQL Schema and resolving those using resolvers when queries get called for data.

Steps to Build GraphQL

• Start with a Schema: It outlines different types, resources and how information gets processed
• Define Resolvers: It helps to map the types and fields to the source of the information it can serve to. For example what endpoints or APIs serve the request.
• Link resolvers to data sources: The actual implementation to link defined resolvers to the data sources.

GraphQL in Azure API Management

There are two ways to implement GraphQL via Azure APIM.

GraphQL Pass-through

You can use this when you already have an existing GraphQL API, which then you can plug in thru Azure APIM, leveraging all the existing benefits of API Management—including security, observability, and reduced latency—for their GraphQL APIs while also adding GraphQL-specific features such as a query test console, query validation, field-based authorization, and query depth and size restriction.

Synthetic GraphQL

With this second approach, Synthetic GraphQL allows you to easily create a GraphQL API based on your existing HTTP (SOAP or REST) APIs. This allows you to quickly upgrade your API to support modern client application development without affecting your existing infrastructure.

• With this availability, you can:
• Change your existing APIs into GraphQL to support modern client application development. Build a GraphQL API from existing SOAP, REST, and other HTTP APIs.
• Augment your existing GraphQL API with third-party APIs such as Microsoft Graph, Dynamics, Shopify, and Zendesk.
• Build your GraphQL API

With the preview GraphQL resolvers, you can remove the GraphQL backend completely and define a complete set of resolvers to fulfil any query. The resolvers can easily be written in Azure Functions or take advantage of REST APIs across M365, Azure, your own services, or third-party services such as Shopify, Marketo, or ServiceNow. The Synthetic GraphQL service will run all the required requests and combine the results into the response to the user.

After explaining the Synthetic GraphQL on Azure APIM, Elizabeth ran thru a really cool demo using SpaceX GraphQL APIs and Azure APIM. She also demonstrated how convenient it is to extend the existing GraphQL with additional HTTP requests.

API Management protects against the top 5 OWASP GraphQL security issues

Briefly, the top 5 security issues with GraphQL were discussed and she also showed how those issues can be mitigated with Azure APIM.

Key Takeaways / Cluster Take

1. Use GraphQL to extend the features without losing your backend APIs investments
2. Production GraphQL is easier and more secure with Azure API Management.
3. Looking back at Toon Vanhoutte's session on APIM, he mentioned the Layered API pattern with an Experience layer that customises lower-level APIs for specific audiences and clients. Rather than hand-rolling these APIs, we can see great opportunities for organisations to leverage the newly-announced Synthetic GraphQL features of Azure APIM to build on existing investment in REST and SOAP APIs and expose a flexible single endpoint to API clients. Synthetic GraphQL APIs will allow API clients to query APIs in a self-service manner to retrieve just the data they need, all without compromising on governance or data security..

If you would like to schedule a workshop to learn more about how you can leverage the Azure APIM to connect with your existing APIs and build a GraphQL on top of them, please reach out to us via our LinkedIn Page or email us at cluster.uk.info@reply.com and we will be happy to guide you on your journey to Azure Adoption.