<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Thisaru Guruge on Medium]]></title>
        <description><![CDATA[Stories by Thisaru Guruge on Medium]]></description>
        <link>https://medium.com/@thisaru?source=rss-ce30d56b8733------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*wzUrAoqNJVxIHlRG.jpg</url>
            <title>Stories by Thisaru Guruge on Medium</title>
            <link>https://medium.com/@thisaru?source=rss-ce30d56b8733------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 23:03:02 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@thisaru/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[GraphQL Federation with Ballerina and Apollo — Part II]]></title>
            <link>https://medium.com/ballerina-techblog/graphql-federation-with-ballerina-and-apollo-part-ii-d05ee4fcd796?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/d05ee4fcd796</guid>
            <category><![CDATA[graphql]]></category>
            <category><![CDATA[authentication]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <category><![CDATA[graphql-federation]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 03 Oct 2023 15:31:21 GMT</pubDate>
            <atom:updated>2023-10-20T05:26:09.663Z</atom:updated>
            <content:encoded><![CDATA[<h3>GraphQL Federation with Ballerina and Apollo — Part II</h3><blockquote>This is part II of the series “GraphQL Federation with Ballerina and Apollo”. Refer to <a href="https://thisaru.medium.com/graphql-federation-with-ballerina-and-apollo-part-i-680f5aeae131">Part I</a> before reading this.</blockquote><p><em>This article was written using Ballerina Swan Lake Update 8 (2201.8.0)</em></p><figure><img alt="GraphQL and Ballerina SwanLake logos" src="https://cdn-images-1.medium.com/max/1024/1*mXcdNppFd3_PO8EdEKDUzg.png" /><figcaption>GraphQL Federation with Ballerina Swan Lake and Apollo</figcaption></figure><p>In the first part, we discussed the GraphQL federation concepts and how to implement federated GraphQL API using Ballerina and Apollo Studio. In this part, we will discuss how to implement Entity types and ReferenceResolvers in Ballerina. Further, we will briefly discuss how to handle authentication and authorization in a federated GraphQL API.</p><h3><strong>Adding Federated Fields</strong></h3><p>We have intentionally left some fields from the subgraph implementations. This is to simplify the supergraph creation process. Now that we have a working supergraph, we can add the missing fields. The beauty of the GraphQL federation is that it reduces the duplication of types. As per our initial GraphQL API, there are types with fields spread across the subgraphs. To add these fields, you need to implement the subgraphs with federation-specific functionalities.</p><blockquote><strong>Note:</strong> In GraphQL federation, you can compose individual, isolated subgraphs into a federated GraphQL schema, as we have done so far. Currently, all our subgraphs are standalone GraphQL services. But to add federation-specific functionalities, we need to mark them specifically as subgraphs.</blockquote><h4><strong>Updating Subgraphs to Federated Subgraphs</strong></h4><p>The ballerina/graphql.subgraph module consists of the functionalities for GraphQL federation. To use these functionalities, you need to import the ballerina/graphql.subgraph module. Then you can mark your GraphQL service as a subgraph using the subgraph:Subgraph annotation.</p><p><strong>Marking the Products Subgraph as a Federated Subgraph</strong></p><p>You need to do the following things:</p><ul><li>Mark the Products subgraph as a federated subgraph</li><li>Mark the Product type as an Entity type</li><li>Provide a ReferenceResolver for the Product type</li></ul><p>First, to mark the Products subgraph as a federated subgraph, you need to add the @subgraph:Subgraph annotation to the GraphQL service.</p><p>Following is the updated GraphQL service code in the Products subgraph.</p><pre>import ballerina/graphql;<br>import ballerina/graphql.subgraph;<br><br>@subgraph:Subgraph<br>service graphql:Service on new graphql:Listener(9091) {<br>    // ...<br>}</pre><p>Basically, what you need to do is to import the ballerina/graphql.subgraph module and add the @subgraph:Subgraph annotation to your existing GraphQL service.</p><p>Now that the product subgraph is marked as a subgraph, we can mark our Product type as an Entity type.</p><p>To mark the Product type as an entity, you need to update the Product type as an Entity type and add a ReferenceResolver for the Product type. Following is the updated Product type definition:</p><pre>import product_subgraph.datasource;<br><br>import ballerina/graphql;<br>import ballerina/graphql.subgraph;<br><br>@subgraph:Entity {<br>  key: &quot;id&quot;,<br>  resolveReference: resolveProduct<br>}<br>public type Product record {|<br>  // same as before<br>}<br><br>isolated function resolveProduct(subgraph:Representation representation) returns Product|error {<br>  string id = check representation[&quot;id&quot;].ensureType();<br>  return datasource:getProduct(id);<br>}</pre><p>Using this, we state that the Product type is an Entity in the federated supergraph, which is to say that this type might have fields included from the other subgraphs. For an Entity, there should be a key to uniquely identify a particular value of that entity type. For the router to identify these specific values, you need to provide which field acts as the key for this entity type. In this case, the id field is used as the key. The rest of the type definition remains the same.</p><p>Then you have to define a ReferenceResolver for the Product type. This is a requirement in the GraphQL federation specification, which states that <em>if a particular subgraph contributes at least a single unique field must implement a reference resolver for that type</em>. A reference resolver takes exactly one input, the subgraph:Representation type. When the GraphQL router sends a request to the subgraph to resolve a particular type using its unique identifier, the Representation type will include that field, in this case, the id field. Then you can retrieve that type from the subgraph:Representation and use that identifier to resolve the value of the type. In this case, we get the id from the representation and return an instance of the Product type. This function is passed as a function pointer in the @subgraph:Entity annotation as the resolveReference field.</p><p>Now the Products subgraph implementation is ready to be published. You can regenerate the GraphQL schema for the Products subgraph using the bal command:</p><pre>bal graphql -i service.bal</pre><p>Then you can publish your updated Products subgraph to the Apollo Studio using the previous command:</p><pre>rover subgraph publish &lt;APOLLO_GRAPH_REF&gt; \<br>-name Products \<br>-schema ./schema_service.graphql \</pre><blockquote><strong>Note:</strong> When publishing the same subgraph for the second time, you don’t need to provide the routing URL of the subgraph, until you need to change it.</blockquote><p><strong>Marking the Users Subgraph as a Federated Subgraph</strong></p><p>You need to do the following things:</p><ul><li>Mark the Users subgraph as a federated subgraph</li><li>Mark the User type as an Entity type</li><li>Provide a ReferenceResolver for the User type</li></ul><p>Marking the Users subgraph as a federated subgraph is similar to the <strong><em>Products Subgraph</em></strong>. Following is the updated GraphQL service code in the Users subgraph.</p><pre>import ballerina/graphql;<br>import ballerina/graphql.subgraph;<br><br>@subgraph:Subgraph<br>service graphql:Service on new graphql:Listener(9091) {<br>  // ...<br>}</pre><p>Then you can mark the User type as an Entity type. Following is the updated User type definition:</p><pre>import user_subgraph.datasource;<br><br>import ballerina/graphql;<br>import ballerina/graphql.subgraph;<br><br>@subgraph:Entity {<br>  key: &quot;id&quot;,<br>  resolveReference: resolveUser<br>}<br>public type User record {|<br>  @graphql:ID string id;<br>  string name;<br>  string email;<br>|};<br><br>isolated function resolveUser(subgraph:Representation representation) returns User|error? {<br>  string id = check representation[&quot;id&quot;].ensureType();<br>  return datasource:getUser(id);<br>}</pre><p>The above code segment shows the subgraph:Entity annotation, the resolveUser function as the reference resolver.</p><p>To facilitate the reference resolver, you need to provide an API to retrieve a User value from the id. In this case, we have a getUser function in the datasource module. Then you can use this function to resolve the User value from the Representation type. Following is the definition of the getUser() API inside the datasource module:</p><pre>public isolated function getUser(string id) returns User? {<br>  lock {<br>    if users.hasKey(id) {<br>      return users.get(id);<br>    }<br>  }<br>  return;<br>}</pre><p>With this, your Users subgraph is ready to be published. You can regenerate the GraphQL schema for the Users subgraph using the bal command:</p><pre>bal graphql -i service.bal</pre><p>Then you can publish your updated Users subgraph to the Apollo Studio using the previous command:</p><pre>rover subgraph publish &lt;APOLLO_GRAPH_REF&gt; \<br>-name Users \<br>-schema ./schema_service.graphql \</pre><p><strong>Marking the Reviews Subgraph as a Federated Subgraph</strong></p><p>Now you are ready to update the review subgraph. To refresh the memory, we need to do the following:</p><ul><li>Mark the GraphQL service as a subgraph</li><li>Add the Product entity type (with reviews field)</li><li>Add the User entity type (with reviews field)</li><li>Add the product field to the Review type</li><li>Add the author field to the Review type</li></ul><p>First, to mark the Reviews subgraph as a federated subgraph, you need to add the @subgraph:Subgraph annotation to the GraphQL service, similar to the previous subgraphs.</p><p>Following is the updated GraphQL service code in the Reviews subgraph.</p><pre>import ballerina/graphql;<br>import ballerina/graphql.subgraph;<br><br>@subgraph:Subgraph<br>service graphql:Service on new graphql:Listener(9093) {<br>  // ...<br>}</pre><p>Then you can add the Product type as an entity. From the Reviews subgraph, we contribute the reviews field to the Product type. Therefore, you only need the id field (which is the key for the Product entity type) and the reviews field. You should also define the reference resolver for the Product type. Following is the Product type definition:</p><pre>@subgraph:Entity {<br>  key: &quot;id&quot;,<br>  resolveReference: resolveProduct<br>}<br>public type Product record {|<br>  @graphql:ID string id;<br>  Review[] reviews;<br>|};<br><br>public isolated function resolveProduct(subgraph:Representation representation) returns Product|error {<br>  string id = check representation[&quot;id&quot;].ensureType();<br>  return getProduct(id);<br>}</pre><p>Similarly, you can define the User type with the reviews field and the corresponding reference resolver. Following is the User type definition:</p><pre>@subgraph:Entity {<br>  key: &quot;id&quot;,<br>  resolveReference: resolveUser<br>}<br>public type User record {|<br>  @graphql:ID string id;<br>  Review[] reviews;<br>|};<br><br>public isolated function resolveUser(subgraph:Representation representation) returns Product|error {<br>  string id = check representation[&quot;id&quot;].ensureType();<br>  return getAuthor(id);<br>}</pre><p>As per the above codes, you need two utility functions to retrieve the Product and User values from the data source. Following are the implementations of those functions:</p><pre>isolated function getProduct(string id) returns Product {<br>  ReviewInfo[] reviewList = datasource:getReviewsByProduct(id);<br>  return {<br>    id,<br>    reviews: reviewList.map(reviewInfo =&gt; new Review(reviewInfo))<br>  };<br>}<br><br>isolated function getAuthor(string id) returns User {<br>  ReviewInfo[] reviewList = datasource:getReviewsByAuthor(id);<br>  return {<br>    id,<br>    reviews: reviewList.map(reviewInfo =&gt; new Review(reviewInfo))<br>  };<br>}</pre><p>To facilitate these functions, you need to add new APIs to the datasource. Following are the implementations of those APIs:</p><pre>public isolated function getReviewsByProduct(string productId) returns readonly &amp; Review[] {<br>  lock {<br>    return from Review review in reviews where review.productId == productId select review;<br>  }<br>}<br><br>public isolated function getReviewsByAuthor(string userId) returns readonly &amp; Review[] {<br>  lock {<br>    return from Review review in reviews where review.authorId == userId select review;<br>  }<br>}</pre><p>Then you have to add the author and product fields to the Review type. This can be easily done by adding two resource methods to the existing Review service class. Following are the two new resource methods:</p><pre>isolated resource function get author() returns User =&gt; getAuthor(self.reviewInfo.authorId);<br>isolated resource function get product() returns Product =&gt; getProduct(self.reviewInfo.productId);</pre><p>Now your Reviews subgraph is ready to be published. You can regenerate the GraphQL schema for the Reviews subgraph using the bal command:</p><pre>bal graphql -i service.bal</pre><p>Then you can publish your updated Reviews subgraph to the Apollo Studio using the previous command:</p><pre>rover subgraph publish &lt;APOLLO_GRAPH_REF&gt; \<br>-name Reviews \<br>-schema ./schema_service.graphql \</pre><p>Now all three subgraphs are updated and published to the Apollo studio. Now if you visit the Apollo Studio and check the generated supergraph schema, you can see the following schemas:</p><ul><li>The GraphQL API schema</li></ul><pre>type Mutation {<br>  addReview(input: ReviewInput!): Review!<br>}<br><br>type Product {<br>  id: ID!<br>  name: String!<br>  description: String!<br>  price: Float!<br>  reviews: [Review!]!<br>}<br><br>type Query {<br>  products: [Product!]!<br>  product(id: ID!): Product<br>  reviews: [Review!]!<br>  users: [User!]<br>}<br><br>type Review {<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  author: User!<br>  product: Product!<br>}<br><br>input ReviewInput {<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  authorId: String!<br>  productId: String!<br>}<br><br>type User {<br>  id: ID!<br>  reviews: [Review!]!<br>  name: String!<br>  email: String!<br>}</pre><ul><li>The composed supergraph schema</li></ul><pre>schema<br>  @link(url: &quot;https://specs.apollo.dev/link/v1.0&quot;)<br>  @link(url: &quot;https://specs.apollo.dev/join/v0.3&quot;, for: EXECUTION)<br>{<br>  query: Query<br>  mutation: Mutation<br>}<br><br>directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE<br><br>directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION<br><br>directive @join__graph(name: String!, url: String!) on ENUM_VALUE<br><br>directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE<br><br>directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true, isInterfaceObject: Boolean! = false) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR<br><br>directive @join__unionMember(graph: join__Graph!, member: String!) repeatable on UNION<br><br>directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA<br><br>scalar join__FieldSet<br><br>enum join__Graph {<br>  PRODUCTS @join__graph(name: &quot;Products&quot;, url: &quot;http://localhost:9091&quot;)<br>  REVIEWS @join__graph(name: &quot;Reviews&quot;, url: &quot;http://localhost:9093&quot;)<br>  USERS @join__graph(name: &quot;Users&quot;, url: &quot;http://localhost:9092&quot;)<br>}<br><br>scalar link__Import<br><br>enum link__Purpose {<br>  &quot;&quot;&quot;<br>  `SECURITY` features provide metadata necessary to securely resolve fields.<br>  &quot;&quot;&quot;<br>  SECURITY<br>  &quot;&quot;&quot;<br>  `EXECUTION` features provide metadata necessary for operation execution.<br>  &quot;&quot;&quot;<br>  EXECUTION<br>}<br><br>type Mutation<br>  @join__type(graph: REVIEWS)<br>{<br>  addReview(input: ReviewInput!): Review!<br>}<br><br>type Product<br>  @join__type(graph: PRODUCTS, key: &quot;id&quot;)<br>  @join__type(graph: REVIEWS, key: &quot;id&quot;)<br>{<br>  id: ID!<br>  name: String! @join__field(graph: PRODUCTS)<br>  description: String! @join__field(graph: PRODUCTS)<br>  price: Float! @join__field(graph: PRODUCTS)<br>  reviews: [Review!]! @join__field(graph: REVIEWS)<br>}<br><br>type Query<br>  @join__type(graph: PRODUCTS)<br>  @join__type(graph: REVIEWS)<br>  @join__type(graph: USERS)<br>{<br>  products: [Product!]! @join__field(graph: PRODUCTS)<br>  product(id: ID!): Product @join__field(graph: PRODUCTS)<br>  reviews: [Review!]! @join__field(graph: REVIEWS)<br>  users: [User!] @join__field(graph: USERS)<br>}<br><br>type Review<br>  @join__type(graph: REVIEWS)<br>{<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  author: User!<br>  product: Product!<br>}<br><br>input ReviewInput<br>  @join__type(graph: REVIEWS)<br>{<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  authorId: String!<br>  productId: String!<br>}<br><br>type User<br>  @join__type(graph: REVIEWS, key: &quot;id&quot;)<br>  @join__type(graph: USERS, key: &quot;id&quot;)<br>{<br>  id: ID!<br>  reviews: [Review!]! @join__field(graph: REVIEWS)<br>  name: String! @join__field(graph: USERS)<br>  email: String! @join__field(graph: USERS)<br>}</pre><p>Now your supergraph schema is complete. You can use the Apollo Router to access your supergraph. If the router is not running already, run it again using the following command:</p><pre>APOLLO_KEY=&lt;Your Apollo Key&gt; APOLLO_GRAPH_REF=&lt;Your Apollo Graph Ref&gt; ./router - config router.yaml</pre><p>Then you can access the supergraph using the following GraphQL document:</p><pre>query ProductReviews {<br>  products {<br>    name<br>    reviews {<br>      rating<br>      author {<br>        name<br>      }<br>    }<br>  }<br>}</pre><p>If everything works as expected, you will get the following response:</p><pre>{<br>  &quot;data&quot;: {<br>    &quot;products&quot;: [<br>      {<br>        &quot;name&quot;: &quot;Shoes&quot;,<br>        &quot;reviews&quot;: []<br>      },<br>      {<br>        &quot;name&quot;: &quot;T-shirt&quot;,<br>        &quot;reviews&quot;: [<br>          {<br>            &quot;rating&quot;: 4,<br>            &quot;author&quot;: {<br>              &quot;name&quot;: &quot;Bob&quot;<br>              }<br>            },<br>            {<br>            &quot;rating&quot;: 3,<br>            &quot;author&quot;: {<br>              &quot;name&quot;: &quot;Charlie&quot;<br>            }<br>          }<br>        ]<br>      },<br>      {<br>        &quot;name&quot;: &quot;Pants&quot;,<br>        &quot;reviews&quot;: [<br>          {<br>            &quot;rating&quot;: 1,<br>            &quot;author&quot;: {<br>              &quot;name&quot;: &quot;Dave&quot;<br>            }<br>          },<br>          {<br>            &quot;rating&quot;: 4,<br>            &quot;author&quot;: {<br>              &quot;name&quot;: &quot;Bob&quot;<br>            }<br>          }<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><p>If you get the above response, congratulations! You have successfully created a federated GraphQL API using Ballerina. You can try out more complex queries to test this further.</p><h3><strong>Handling Auth</strong></h3><p>In a production environment, you might need to handle authentication and authorization. In this section, we will discuss how to handle authentication and authorization in a federated GraphQL API.</p><h4><strong>Authentication</strong></h4><p>There are a few options/approaches for authentication for federated GraphQL APIs. In this article, we will discuss how to use the delegate method. In this approach, you will delegate the authentication to the subgraphs, without handling them at the router-level.</p><blockquote><strong>Note:</strong> There are other approaches where the authentication is handled at the router-level, but those are Apollo federation enterprise specific features. Therefore we are not going to discuss those approaches in this article. Refer to <a href="https://www.apollographql.com/docs/technotes/TN0004-router-authentication">Apollo documentation</a> for more information.</blockquote><p><strong>Configure the Router to Delegate Authentication</strong></p><p>To delegate the authentication to the subgraphs, you need to forward the headers to the subgraphs. To do this, you need to add the following configuration to the router.yaml file:</p><pre>headers:<br>  all:<br>    request:<br>      - propagate:<br>          named: authorization</pre><p>This will forward the authorization header value to each subgraph.</p><p><strong>Implement Authentication in the Subgraphs</strong></p><p>In each subgraph, you can define a contextInit function to retrieve the authorization header value. Following is the implementation of the contextInit function in the Products subgraph:</p><pre>import ballerina/graphql;<br>import ballerina/http;<br><br>@graphql:ServiceConfig {<br>  contextInit: contextInit<br>}<br>service graphql:Service on new graphql:Listener(9091) {<br>  // same as before<br>}<br><br>isolated function contextInit((http:RequestContext requestContext, http:Request request) returns graphql:Context|error {<br>  graphql:Context context = new;<br>  string|error authHeader = request.getHeader(&quot;authorization&quot;);<br>  if authHeader is error {<br>    return error(&quot;Authorization failed&quot;);<br>  }<br>  UserContext|error userContext = authenticateUser(authHeader); // authenticate the user using the authHeader<br>  if userContext is error {<br>    return error(&quot;Authorization failed&quot;);<br>  }<br>  context.set(&quot;user&quot;, userContext);<br>  return context;<br>}</pre><p>In the contextInit function, we are trying to authenticate the user using the authorization header value. If the authentication is successful, we are setting the UserContext to the GraphQL context. Note that we are using the authenticateUser method, which can be implemented according to your authentication mechanism.</p><p>After authenticating the user, the UserContext is passed to the GraphQL context. Using the UserContext, you can implement the authorization logic in the resolvers. In GraphQL, you can configure what fields are accessible to a particular user. In Ballerina this can be achieved using the Interceptors. Following is an example of an interceptor:</p><pre>import ballerina/graphql;<br><br>@graphql:InterceptorsConfig {<br>  global: false<br>}<br>readonly service class AdminAuthInterceptor {<br>  *graphql:Interceptor;<br>  isolated remote function execute(graphql:Context context, graphql:Field &#39;field) returns anydata|error {<br>    UserContext user = check context.get(&quot;user&quot;).ensureType();<br>    if userContext.role != &quot;admin&quot; {<br>      return error(&quot;Unauthorized&quot;);<br>    }<br>  return context.resolve(&#39;field);<br>}</pre><p>The above interceptor handles the authorization logic for the admin role. You can implement other interceptors for other roles as well. Then you can add these interceptors to the resolvers. Following is an example of adding an interceptor to a resolver:</p><pre>service graphql:Service on new graphql:Listener(9091) {<br>  // same as before<br>  @graphql:ResolverConfig {<br>    interceptors: [new AdminAuthInterceptor()]<br>  }<br>  isolated remote function getProduct(string id) returns Product|error {<br>    // same as before<br>  }<br>}</pre><p>We can follow the same approach for the other subgraphs as well. Now you have a federated GraphQL API with authentication and authorization.</p><p>Apart from this, you can also handle authentication using a gateway. In this case, the gateway itself authenticates the user and returns errors if the authentication fails.</p><p>In production environments, you can use a combination of these approaches to handle authentication and authorization, which will provide a more robust authentication and authorization mechanism.</p><h3><strong>Conclusion</strong></h3><p>In this article, we discussed the GraphQL federation concepts and how to implement federated GraphQL API using Ballerina and Apollo Studio, with authentication and authorization.</p><p>There are more exciting projects coming up in the Ballerina GraphQL ecosystem, including:</p><ul><li>The Ballerina GraphQL federation gateway</li><li>The Ballerina GraphQL schema registry</li><li>The federation support for the Ballerina GraphQL CLI tool</li></ul><p>Stay tuned for more updates!</p><h3><strong>References</strong></h3><p>The complete code for the subgraphs can be found in the following repositories:</p><ul><li><a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-products-subgraph/">Products Subgraph</a></li><li><a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-users-subgraph/">Users Subgraph</a></li><li><a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-reviews-subgraph/">Reviews Subgraph</a></li></ul><blockquote>Ballerina is an open-source project. We welcome any kind of contributions to the Ballerina platform, including <a href="https://github.com/ballerina-platform/module-ballerina-graphql"><strong><em>starring</em></strong> <strong><em>on GitHub</em></strong>.</a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d05ee4fcd796" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/graphql-federation-with-ballerina-and-apollo-part-ii-d05ee4fcd796">GraphQL Federation with Ballerina and Apollo — Part II</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[GraphQL Federation with Ballerina and Apollo — Part I]]></title>
            <link>https://medium.com/ballerina-techblog/graphql-federation-with-ballerina-and-apollo-part-i-680f5aeae131?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/680f5aeae131</guid>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[graphql-federation]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <category><![CDATA[architecture]]></category>
            <category><![CDATA[graphql]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Mon, 02 Oct 2023 15:26:23 GMT</pubDate>
            <atom:updated>2025-06-28T16:25:53.256Z</atom:updated>
            <content:encoded><![CDATA[<h3><strong>GraphQL Federation with Ballerina and Apollo — Part I</strong></h3><p><em>This article was written using Ballerina Swan Lake Update 8 (2201.8.0)</em></p><h3><strong>Introduction</strong></h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mXcdNppFd3_PO8EdEKDUzg.png" /></figure><h4><strong>GraphQL: Striking a Balance Between Advantages and Limitations</strong></h4><p><a href="https://spec.graphql.org/October2021//">GraphQL</a>, a relatively recent addition to the API world, is in a constant process of evolution. Like any innovation, GraphQL possesses strengths and limitations that the dynamic GraphQL community aggressively addresses. Within GraphQL APIs, a key benefit is the accessibility of data from a single endpoint. Clients request exactly what they need, and the server responds with exactly the requested information. While this presents an appealing prospect for front-end developers, the same feature can turn into a nightmare for back-end developers. Imagine a GraphQL API with hundreds of types, each with multiple fields. Managing such an API would become an almost insurmountable challenge.</p><h4><strong>Introducing GraphQL Federation: Unifying Complex APIs</strong></h4><p>Enter GraphQL Federation — an architectural paradigm. GraphQL Federation resolves the aforementioned issue by segmenting a singular GraphQL API into smaller components, known as subgraphs. These subgraphs, manageable and scalable, can be differentiated based on the separation of concerns. Various teams can then oversee different subgraphs, with GraphQL Federation seamlessly integrating them into a unified GraphQL API. This ensures a seamless experience for clients, harmonizing the intricacies behind the scenes, while making life easy for the back-end developers.</p><p>This article series will dive into GraphQL federation with Ballerina and Apollo Studio.</p><h4><strong>How Does GraphQL Federation Work?</strong></h4><p>GraphQL Federation consists of 4 major components.</p><ul><li>Subgraph(s)</li><li>Supergraph Schema</li><li>GraphQL Router</li><li>Schema Registry</li></ul><p><strong>Federated Subgraph</strong></p><p>A federated subgraph functions as an independent GraphQL API, typically centered around a specific domain. Typically, a subgraph is overseen by a single team, with distinct implementation details and design preferences, encompassing choices related to data sources, programming languages, and deployment strategies. A federated supergraph, in turn, incorporates one or more of these subgraphs.</p><blockquote><strong>Note:</strong> It’s worth highlighting that GraphQL Federation permits the creation of a federated GraphQL service with a single subgraph. This approach offers scalability for greenfield projects, allowing seamless expansion. For brownfield projects, it facilitates a transition from a monolithic GraphQL API to a Federated GraphQL API.</blockquote><p><strong>Supergraph Schema</strong></p><p>The supergraph schema is a GraphQL schema that encompasses all the subgraphs within the federation. Constructing the supergraph schema entails the composition of all individual subgraphs. A tool like <a href="https://www.apollographql.com/docs/rover/">Rover CLI</a> possesses the capability to seamlessly combine these subgraphs into a supergraph schema.</p><blockquote><strong>Note:</strong> In a later section of this article series, you will delve into the intricacies of the supergraph composition process.</blockquote><p><strong>GraphQL Router</strong></p><p>The GraphQL router is the magical mediator between the GraphQL client and the subgraphs. True to its name, the router efficiently directs GraphQL requests from clients to their respective subgraphs. Particularly in scenarios involving numerous subgraphs with complex relationships, the router is smart enough to devise a query plan to gather necessary data from each subgraph by referring to the supergraph schema. Once the data is collected from these subgraphs, the router stitches them together, generating a singular response dispatched back to the client. This seamless orchestration ensures that the client’s request is fulfilled precisely, all the while being blissfully unaware that the data has been seamlessly curated from multiple GraphQL APIs (subgraphs).</p><p><strong>Schema Registry</strong></p><p>In a federated architecture, the schema registry assumes the role of a version control system for the schema. This registry diligently records alterations made to the federated supergraph schema, ensuring efficient management and conflict reduction while safeguarding the integrity of the supergraph schema.</p><h3><strong>What You’ll Build</strong></h3><p>You will build a product review system using <a href="https://ballerina.io/">Ballerina</a> and <a href="https://www.apollographql.com/docs/federation/">Apollo Federation</a> in this example.</p><p>This service should provide the functionality to retrieve product information, user information, and review information. Additionally, it should provide the functionality to add new reviews to the products.</p><p>Although you are going to implement a federated GraphQL API, first you are going to define the GraphQL schema disregarding the federation aspect. Once the API is defined, it can be broken down into smaller subgraphs.</p><h4><strong>Gathering Requirements</strong></h4><p>To define our GraphQL API effectively, it’s crucial to start by gathering the requirements. The best way to do this is by articulating the use cases. Below, we present a set of simple, sample use cases that will guide the creation of our GraphQL API.</p><p><strong>Use Case 1 — Retrieve Product Information</strong></p><p>The first use case addresses the need for clients to retrieve a list of all products available. This is the GraphQL query for that purpose:</p><pre>query GetAllProducts {<br>  products {<br>    id<br>    name<br>    reviews {<br>      rating<br>    }<br>  }<br>}</pre><p>Additionally, we must cater to the requirement of retrieving a specific product by its unique ID. This is the corresponding GraphQL query:</p><pre>query GetProduct($id: ID!) {<br>  product(id: $id) {<br>    id<br>    name<br>    description<br>    price<br>    reviews {<br>      title<br>      rating<br>      comment<br>    }<br>  }<br>}</pre><p><strong>Use Case 2 — Retrieve User Information</strong></p><p>In the second use case, clients need to fetch a list of all users within the system. The GraphQL query for this purpose is as follows:</p><pre>query GetUsers {<br>  users {<br>    id<br>    name<br>    email<br>  }<br>}</pre><p><strong>Use Case 3 — Retrieve Review Information</strong></p><p>This scenario involves retrieving product review information, filtered either by user ID or product ID. Here are the GraphQL queries for these situations:</p><p>For reviews filtered by user ID:</p><pre>query GetReviews($userId: ID) {<br>  reviews(userId: $userId) {<br>    title<br>    comment<br>    rating<br>  }<br>}</pre><p>For reviews filtered by product ID:</p><pre>query GetReviews($productId: ID) {<br>  reviews(productId: $productId) {<br>    title<br>    comment<br>    rating<br>    author {<br>      id<br>      name<br>    }<br>  }<br>}</pre><p><strong>Use Case 4 — Add Review</strong></p><p>The final use case entails adding a new review to a product. This is achieved through a mutation operation, and the GraphQL mutation looks like this:</p><pre>mutation AddReview($input: ReviewInput!) {<br>  addReview(reviewInput: $input): Review!<br>}</pre><p>Where following is a sample ReviewInput:</p><pre>{<br>  &quot;input&quot;: {<br>    &quot;title&quot;: &quot;Nice Product&quot;,<br>    &quot;comment&quot;: &quot;Value for money&quot;,<br>    &quot;rating&quot;: 5<br>  }<br>}</pre><h4><strong>Designing the API</strong></h4><p>Now that we have a clear understanding of the requirements through these use cases, we can proceed to define the schema for our GraphQL API. Building upon these use cases, we can derive the following GraphQL schema:</p><pre>type Query {<br>  products: [Product!]!<br>  product(id: ID!): Product<br>  users: [User!]!<br>  reviews(productId: ID, authorId: ID): [Review!]!<br>}<br><br>type Mutation {<br>  addReview(reviewInput: ReviewInput!): Review<br>}<br><br>type Product {<br>  id: ID!<br>  name: String!<br>  price: Float!<br>  description: String!<br>  reviews: [Review!]!<br>}<br><br>type Review {<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  product: Product!<br>  author: User!<br>}<br><br>type User {<br>  id: ID!<br>  name: String!<br>  email: String!<br>  reviews: [Review!]!<br>}<br><br>input ReviewInput {<br>  title: String!<br>  comment: String!<br>  productId: ID!<br>}</pre><p>With our GraphQL API schema defined based on the gathered requirements, we can now proceed to the next step.</p><h4><strong>Designing the Federated Supergraph</strong></h4><p>To transform our GraphQL schema into a federated supergraph, we employ a separation of concerns approach. The schema can be logically divided into three main areas: <strong>Products</strong>, <strong>Users</strong>, and <strong>Reviews</strong>. Each of these areas can be implemented as a separate subgraph, often managed by different teams.</p><p>It’s important to note that in a federated GraphQL API, there may be types that span multiple subgraphs. These types are referred to as Entity types in GraphQL federation. To identify Entity types in our schema, we can annotate the schema with subgraph affiliations as comments.</p><blockquote><strong>Note:</strong> These comments are for illustrative purposes only. They are not part of the GraphQL schema and they will not affect the schema in any way.</blockquote><pre>type Query {<br>  products: [Product!]! # Products Subgraph<br>  product(id: ID!): Product # Products Subgraph<br>  users: [User!]! # Users Subgraph<br>  reviews(productId: ID, authorId: ID): [Review!]! # Reviews Subgraph<br>}<br><br>type Mutation {<br>  addReview(reviewInput: ReviewInput!): Review # Reviews Subgraph<br>}<br><br>type Product {<br>  id: ID! # Products Subgraph<br>  name: String! # Products Subgraph<br>  price: Float! # Products Subgraph<br>  description: String! # Products Subgraph<br>  reviews: [Review!]! # Reviews Subgraph<br>}<br><br>type Review {<br>  id: ID! # Reviews Subgraph<br>  title: String! # Reviews Subgraph<br>  comment: String! # Reviews Subgraph<br>  rating: Int! # Reviews Subgraph<br>  product: Product! # Reviews Subgraph<br>  author: User! # Reviews Subgraph<br>}<br><br>type User {<br>  id: ID! # Users Subgraph<br>  name: String! # Users Subgraph<br>  email: String! # Users Subgraph<br>  reviews: [Review!]! # Reviews Subgraph<br>}<br><br>input ReviewInput {<br>  title: String! # Reviews Subgraph<br>  comment: String! # Reviews Subgraph<br>  productId: ID! # Reviews Subgraph<br>}</pre><p>This annotation practice helps us understand the schema’s design and the affiliation of types with different subgraphs.</p><p>In our schema, we have identified two Entity types:</p><ul><li>Product — This type spans both the <strong>Products Subgraph</strong> and the <strong>Reviews Subgraph</strong>.</li><li>User — Similarly, the User type spans both the <strong>Users Subgraph</strong> and the <strong>Reviews Subgraph</strong>.</li></ul><p>Now, with a well-structured GraphQL schema in place, we are ready to proceed to the next step of designing the federated supergraph.</p><h3><strong>Implementing Federated Subgraphs in Ballerina</strong></h3><p>In this section, we’ll walk through the process of implementing individual subgraphs using Ballerina. Each subgraph corresponds to a specific domain within our federated GraphQL API. We’ll create three subgraphs: Products Subgraph, Users Subgraph, and Reviews Subgraph.</p><h4><strong>Prerequisites</strong></h4><ul><li><a href="https://ballerina.io/downloads">Ballerina</a></li><li>A code editor (<a href="https://code.visualstudio.com/">Visual Studio Code</a> is preferred with <a href="https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina">Ballerina extension</a>)</li><li>An <a href="https://studio.apollographql.com/">Apollo Studio</a> account</li><li><a href="https://www.apollographql.com/docs/rover/">Rover CLI</a></li></ul><blockquote><strong>Note: </strong>This article series is written based on the Ballerina Swan Lake Update 8 (2201.8.0) release.</blockquote><p>Before diving into the code, it’s worth noting that this section provides a high-level overview of the subgraph implementations. Detailed code explanations are omitted to maintain focus on the key concepts of GraphQL federation. For in-depth Ballerina GraphQL implementation, refer to the provided resources.</p><h4><strong>Resources for Ballerina GraphQL Implementation</strong></h4><p>For a comprehensive understanding of Ballerina GraphQL implementation, explore these resources:</p><ul><li><a href="https://ballerina.io/spec/graphql">Ballerina GraphQL Specification</a></li><li><a href="https://lib.ballerina.io/ballerina/graphql/latest">Ballerina GraphQL API Docs</a></li><li><a href="https://ballerina.io/learn/by-example/#graphql-service">Ballerina by Examples</a></li></ul><p>Now, let’s proceed with creating the subgraphs without the federation-specific features. We’ll add federation-specific functionality later in this article series.</p><h4><strong>Products Subgraph</strong></h4><p><strong>Schema for the Products Subgraph</strong></p><p>We begin by defining the GraphQL schema for the Products Subgraph, which includes two query fields.</p><pre>type Query {<br>  products: [Product!]!<br>  product(id: ID!): Product<br>}<br><br>type Product {<br>  id: ID!<br>  name: String!<br>  description: String!<br>  price: Float!<br>}</pre><p>To create the Products Subgraph project, use the following Ballerina command:</p><pre>bal new products_subgraph -t service</pre><p>This command initializes a new Ballerina project under the products_subgraph directory.</p><p><strong>Data Source for the Products Subgraph</strong></p><p>Most GraphQL services have their own data sources. In this example, we use an in-memory Ballerina table as the data source, but this can be easily replaced with a database. To make the data source replaceable, we implement it as a separate Ballerina module.</p><p>To add the data source module, navigate to the root directory of the Products subgraph repository and execute this command:</p><pre>bal add datasource</pre><p>This command creates a new datasource directory under the modules directory. Inside this directory, add the following code:</p><p><strong>Types Used in Products Data Source</strong></p><p>Define a single type, Product, used in the data source:</p><pre>type Product readonly &amp; record {|<br>  string id;<br>  string name;<br>  string description;<br>  float price;<br>|};</pre><p><strong>Products Data Source API</strong></p><p>Implement the data source API, which provides access to the product data:</p><pre>public isolated function getProducts() returns readonly &amp; Product[] {<br>  lock {<br>    return from Product product in products select product;<br>  }<br>}<br><br>public isolated function getProduct(string id) returns Product? {<br>  lock {<br>    return products[id];<br>  }<br>}</pre><p><strong>Sample Product Data</strong></p><p>Define a sample data set for the Product type:</p><pre>isolated table&lt;Product&gt; key(id) products = table [<br>  {id: &quot;product_0&quot;, name: &quot;Shoes&quot;, description: &quot;A pair of shoes&quot;, price: 100},<br>  {id: &quot;product_1&quot;, name: &quot;T-shirt&quot;, description: &quot;A t-shirt&quot;, price: 10},<br>  {id: &quot;product_2&quot;, name: &quot;Pants&quot;, description: &quot;A pair of pants&quot;, price: 50}<br>];</pre><p><strong>GraphQL Service for Products Subgraph</strong></p><p>Now, let’s create the main GraphQL service for the Products Subgraph. Below is the initial code for this subgraph service:</p><pre>import product_subgraph.datasource;<br><br>import ballerina/graphql;<br><br>service graphql:Service on new graphql:Listener(9091) {<br>  resource function get products() returns Product[] =&gt; datasource:getProducts();<br><br>  resource function get product(@graphql:ID string id) returns Product? =&gt;<br>  datasource:getProduct(id);<br>}</pre><p><strong>Types of the Products Subgraph</strong></p><p>The next step is to define the types required for the GraphQL service of the Products Subgraph. In this case, we have a single type, Product:</p><pre>import ballerina/graphql;<br><br>public type Product record {|<br>  @graphql:ID string id;<br>  string name;<br>  string description;<br>  float price;<br>|};</pre><p>For the detailed implementation of this subgraph, refer to the <a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-products-subgraph/tree/initial-state">Products Subgraph repository</a>.</p><h4><strong>Users Subgraph</strong></h4><p>The Users Subgraph follows a similar structure as the Products Subgraph. Here, we’ll define the schema, data source, GraphQL service, and types for the Users Subgraph.</p><p><strong>Schema for the Users Subgraph</strong></p><p>Define the GraphQL schema for the Users Subgraph, which includes a single query field:</p><pre>type Query {<br>  users: [User!]!<br>}<br><br>type User {<br>  id: ID!<br>  name: String!<br>  email: String!<br>}</pre><p>To create the Users Subgraph project, follow the same steps as the Products Subgraph and execute this command:</p><pre>bal new users_subgraph -t service</pre><p><strong>Data Source for the Users Subgraph</strong></p><p>Create a data source module for the Users Subgraph, similar to the Products Subgraph, with types, data source API, and sample user data.</p><p><strong>Types Used in Users Data Source</strong></p><p>Define the User type for the data source:</p><pre>public type User record {|<br>  string id;<br>  string name;<br>  string email;<br>|};</pre><p><strong>Users Data Source API</strong></p><p>Implement the data source API for accessing user data:</p><pre>public isolated function getUsers() returns readonly &amp; User[] {<br>  lock {<br>    return from User user in users select user;<br>  }<br>}</pre><p><strong>Sample User Data</strong></p><p>Define a sample data set for the User type:</p><pre>isolated table&lt;User&gt; key(id) users = table [<br>  {id: &quot;user_0&quot;, name: &quot;Alice&quot;, email: &quot;alice@sample.com&quot;},<br>  {id: &quot;user_1&quot;, name: &quot;Bob&quot;, email: &quot;bob@sample.com&quot;},<br>  {id: &quot;user_2&quot;, name: &quot;Charlie&quot;, email: &quot;charlie@sample.com&quot;},<br>  {id: &quot;user_3&quot;, name: &quot;Dave&quot;, email: &quot;dave@sample.com&quot;},<br>  {id: &quot;user_4&quot;, name: &quot;Eve&quot;, email: &quot;eve@sample.com&quot;}<br>];</pre><p><strong>GraphQL Service for Users Subgraph</strong></p><p>Create the GraphQL service for the Users Subgraph:</p><pre>import user_subgraph.datasource;<br><br>import ballerina/graphql;<br><br>service graphql:Service on new graphql:Listener(9092) {<br>  resource function get users() returns User[] =&gt; datasource:getUsers();<br>}</pre><p><strong>Types of the Users Subgraph</strong></p><p>Define the GraphQL types for the Users Subgraph, including the User type:</p><pre>import ballerina/graphql;<br><br>public type User record {|<br>  @graphql:ID string id;<br>  string name;<br>  string email;<br>|};</pre><p>The Users Subgraph implementation details can be found in the <a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-users-subgraph/tree/initial-state">Users Subgraph repository</a>.</p><h4><strong>Reviews Subgraph</strong></h4><p>The Reviews Subgraph follows a similar structure as the previous subgraphs. Here, we’ll define the schema, data source, GraphQL service, and types for the Reviews Subgraph.</p><p><strong>Schema for the Reviews Subgraph</strong></p><p>Define the GraphQL schema for the Reviews Subgraph, which includes queries and a mutation for adding reviews:</p><pre>type Query {<br>  reviews: [Review!]!<br>}<br><br>type Review {<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>}<br><br>type Mutation {<br>  addReview(input: ReviewInput!): Review!<br>}<br><br>input ReviewInput {<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  authorId: String!<br>  productId: String!<br>}</pre><blockquote><strong>Note:</strong> The product and the author fields of the Review type are not added here. Those fields will be added in a later section of this article series.</blockquote><p>To create the Reviews Subgraph project, follow the same steps as the previous subgraphs and execute this command:</p><pre>bal new reviews_subgraph -t service</pre><p><strong>Data Source for the Reviews Subgraph</strong></p><p>Create a data source module for the Reviews Subgraph, similar to the previous subgraphs, with types, data source API, and sample review data.</p><p><strong>Types Used in Reviews Data Source</strong></p><p>Define two types of the data source: Review and ReviewInput:</p><pre>type Review record {|<br>  readonly string id;<br>  string title;<br>  string comment;<br>  int rating;<br>  string authorId;<br>  string productId;<br>|};<br><br>type ReviewInput record {|<br>  string title;<br>  string comment;<br>  int rating;<br>  string authorId;<br>  string productId;<br>|};</pre><p><strong>Reviews Data Source API</strong></p><p>Implement the data source API for accessing review data and adding new reviews:</p><pre>public isolated function getReviews() returns readonly &amp; Review[] {<br>  lock {<br>    return from Review review in reviews select review;<br>  }<br>}<br><br>public isolated function addReview(ReviewInput input) returns Review {<br>  lock {<br>    string nextId = string `review-${reviews.length()}`;<br>    Review review = {<br>      id: nextId,<br>      ...input<br>    };<br>    reviews.add(review);<br>    return review;<br>  }<br>}</pre><p><strong>Sample Review Data</strong></p><p>Define a sample data set for the Review type:</p><pre>isolated table&lt;Review&gt; key(id) reviews = table [<br>  {id: &quot;review_0&quot;, title: &quot;Great!&quot;, comment: &quot;Value for money&quot;, rating: 4, productId: &quot;product_1&quot;, authorId: &quot;user_1&quot;},<br>  {id: &quot;review_1&quot;, title: &quot;Good&quot;, comment: &quot;Fast delivery&quot;, rating: 3, productId: &quot;product_1&quot;, authorId: &quot;user_2&quot;},<br>  {id: &quot;review_2&quot;, title: &quot;Bad&quot;, comment: &quot;Not as described&quot;, rating: 1, productId: &quot;product_2&quot;, authorId: &quot;user_3&quot;},<br>  {id: &quot;review_3&quot;, title: &quot;Great!&quot;, comment: &quot;Value for money&quot;, rating: 4, productId: &quot;product_2&quot;, authorId: &quot;user_1&quot;}<br>];</pre><p><strong>GraphQL Service for Reviews Subgraph</strong></p><p>Create the GraphQL service for the Reviews Subgraph, including query and mutation operations:</p><pre>import review_subgraph.datasource;<br><br>import ballerina/graphql;<br><br>service graphql:Service on new graphql:Listener(9093) {<br>  resource function get reviews() returns Review[] {<br>    return from ReviewInfo reviewInfo in datasource:getReviews()<br>    select new (reviewInfo);<br>  }<br><br>  remote function addReview(ReviewInput input) returns Review {<br>    ReviewInfo result = datasource:addReview(input);<br>    return new (result);<br>  }<br>}</pre><p><strong>Types of the Reviews Subgraph</strong></p><p>Define the GraphQL types for the Reviews Subgraph, including the Review type and ReviewInput input type:</p><pre>import ballerina/constraint;<br>import ballerina/graphql;<br><br>public isolated service class Review {<br>  private final readonly &amp; ReviewInfo reviewInfo;<br><br>  isolated function init(ReviewInfo reviewInformation) {<br>    self.reviewInfo = reviewInformation.cloneReadOnly();<br>  }<br><br>  isolated resource function get id() returns @graphql:ID string =&gt; self.reviewInfo.id;<br>  isolated resource function get title() returns string =&gt; self.reviewInfo.title;<br>  isolated resource function get comment() returns string =&gt; self.reviewInfo.comment;<br>  isolated resource function get rating() returns int =&gt; self.reviewInfo.rating;<br>}<br><br>type ReviewInfo record {|<br>  string id;<br>  string title;<br>  string comment;<br>  int rating;<br>  string authorId;<br>  string productId;<br>|};<br><br>public type ReviewInput readonly &amp; record {|<br>  string title;<br>  string comment;<br>  @constraint:Int {<br>    minValue: 0,<br>    maxValue: 5<br>  }<br>  int rating;<br>  string authorId;<br>  string productId;<br>|};</pre><blockquote><strong>Note:</strong> The Review type is defined using a Ballerina service type here. Although it could be defined using a record type, the service type is chosen because certain federation-specific features (which will be discussed later in this article series) require this type to be defined as a service type.</blockquote><p>For a detailed implementation of this subgraph, refer to the <a href="https://github.com/ThisaruGuruge/ballerina-graphql-federation-reviews-subgraph/tree/initial-state">Reviews Subgraph repository</a>.</p><p>With these subgraphs implemented, you have laid the foundation for your federated GraphQL API. In the next sections, we will enhance these subgraphs with federation-specific features to build the supergraph.</p><h3><strong>Publish Subgraphs</strong></h3><p>Now that we have our initial implementation complete, we can publish them. To publish the subgraphs we can use the <a href="https://www.apollographql.com/docs/rover/">Rover CLI</a> from Apollo.</p><h4><strong>Publishing to Apollo Studio</strong></h4><p>To publish the subgraphs to Apollo Studio, first, create an account on Apollo Studio and create a new Graph. Refer to <a href="https://www.apollographql.com/docs/graphos/">Apollo documentation</a> for more information about creating new graphs and publishing them. When you create a new Graph, a pop-up shows up with an APOLLO_KEY, and APOLLO_GRAPH_REF. Copy these values and save them in a .env file.</p><pre>APOLLO_KEY=&lt;Your Apollo Key&gt;<br>APOLLO_GRAPH_REF=&lt;Your Apollo Graph Ref&gt;</pre><p>First, we need to configure the Rover CLI to connect with our Graph in the Apollo Studio. Execute the following command to configure the Rover CLI.</p><pre>rover config auth</pre><p>This will prompt you to enter the Apollo key. Copy and paste the APOLLO_KEY obtained above here.</p><blockquote><strong>Note:</strong> Make sure to copy and paste the complete key, which starts from service:.</blockquote><p>If the key is applied successfully, the following message will be printed on the stdout:</p><pre>Successfully saved API key.</pre><p>Once the key is successfully set, we can publish the subgraph.</p><p>To publish the subgraph we need the GraphQL schema of the subgraph. To get the subgraph, we can use the <a href="https://ballerina.io/learn/graphql-tool/#schema-generation">bal graphql CLI tool</a>. Execute the following command inside the <strong>Products subgraph</strong> repo:</p><pre>bal graphql -i service.bal</pre><p>This will generate the GraphQL schema for the subgraph and save it in a file named schema_service.graphql. Once the schema is created, you can publish the subgraph to Apollo Studio. For testing purposes, we can use the locally running subgraph for this. Execute the following command in the root of the Products subgraph repository:</p><pre>bal run</pre><p>This will run the GraphQL service locally. Now that we have a running instance of the subgraph, we can publish it to the Apollo studio using Rover CLI. You need the APOLLO_GRAPH_REF obtained above for this step. Execute the following command to publish the subgraph:</p><pre>rover subgraph publish &lt;APOLLO_GRAPH_REF&gt; \<br>-name Products \<br>-schema ./schema_service.graphql \<br>-routing-url http://localhost:9091</pre><p>Repeat the same steps for the other two subgraphs to publish them to Apollo Studio.</p><blockquote><strong>Note:</strong> You do not need to configure the Rover CLI every time. When publishing just change the subgraph name, schema file, and the url accordingly.</blockquote><p>Once all the subgraphs are published, we can visit the Apollo Studio and check our schema. Following is a sample GraphQL API schema generated in the Apollo Studio:</p><pre>type Mutation {<br>  addReview(input: ReviewInput!): Review!<br>}<br><br>type Product {<br>  id: ID!<br>  name: String!<br>  description: String!<br>  price: Float!<br>}<br><br>type Query {<br>  products: [Product!]!<br>  product(id: ID!): Product<br>  reviews: [Review!]!<br>  users: [User!]!<br>}<br><br>type Review {<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>}<br><br>input ReviewInput {<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  authorId: String!<br>  productId: String!<br>}<br><br>type User {<br>  id: ID!<br>  name: String!<br>  email: String!<br>}</pre><p>In addition to this schema, there will be another schema generated from the Apollo Studio, which is our supergraph schema. Following is the supergraph schema generated from the subgraphs we published above:</p><pre>schema<br>  @link(url: &quot;https://specs.apollo.dev/link/v1.0&quot;)<br>  @link(url: &quot;https://specs.apollo.dev/join/v0.3&quot;, for: EXECUTION)<br>{<br>  query: Query<br>  mutation: Mutation<br>}<br><br>directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE<br><br>directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION<br><br>directive @join__graph(name: String!, url: String!) on ENUM_VALUE<br><br>directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE<br><br>directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true, isInterfaceObject: Boolean! = false) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR<br><br>directive @join__unionMember(graph: join__Graph!, member: String!) repeatable on UNION<br><br>directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA<br><br>scalar join__FieldSet<br><br>enum join__Graph {<br>  PRODUCTS @join__graph(name: &quot;Products&quot;, url: &quot;http://localhost:9091&quot;)<br>  REVIEWS @join__graph(name: &quot;Reviews&quot;, url: &quot;http://localhost:9093&quot;)<br>  USERS @join__graph(name: &quot;Users&quot;, url: &quot;http://localhost:9092&quot;)<br>}<br><br>scalar link__Import<br><br>enum link__Purpose {<br>  &quot;&quot;&quot;<br>  `SECURITY` features provide metadata necessary to securely resolve fields.<br>  &quot;&quot;&quot;<br>  SECURITY<br>  &quot;&quot;&quot;<br>  `EXECUTION` features provide metadata necessary for operation execution.<br>  &quot;&quot;&quot;<br>  EXECUTION<br>}<br><br>type Mutation<br>  @join__type(graph: REVIEWS)<br>{<br>  addReview(input: ReviewInput!): Review!<br>}<br><br>type Product<br>  @join__type(graph: PRODUCTS)<br>{<br>  id: ID!<br>  name: String!<br>  description: String!<br>  price: Float!<br>}<br><br>type Query<br>  @join__type(graph: PRODUCTS)<br>  @join__type(graph: REVIEWS)<br>  @join__type(graph: USERS)<br>{<br>  products: [Product!]! @join__field(graph: PRODUCTS)<br>  product(id: ID!): Product @join__field(graph: PRODUCTS)<br>  reviews: [Review!]! @join__field(graph: REVIEWS)<br>  users: [User!]! @join__field(graph: USERS)<br>}<br><br>type Review<br>  @join__type(graph: REVIEWS)<br>{<br>  id: ID!<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>}<br><br>input ReviewInput<br>  @join__type(graph: REVIEWS)<br>{<br>  title: String!<br>  comment: String!<br>  rating: Int!<br>  authorId: String!<br>  productId: String!<br>}<br><br>type User<br>  @join__type(graph: USERS)<br>{<br>  id: ID!<br>  name: String!<br>  email: String!<br>}</pre><p>As you can see, the Apollo Studio already has composed a supergraph schema from the subgraphs you published. Now that we have the supergraph ready, we can use the Apollo Router as the access point of our supergraph.</p><blockquote><strong>Note:</strong> You can compose your supergraph schema locally using the Rover CLI. Refer to <a href="https://www.apollographql.com/docs/rover/supergraphs/#composing-a-supergraph-schema">Apollo documentation</a> for more information.</blockquote><h4><strong>Configure Apollo Router</strong></h4><p>Create a new directory and download the <a href="https://www.apollographql.com/docs/router/quickstart/#1-download-and-extract-the-apollo-router-binary">Apollo Router</a>.</p><blockquote><strong>Note:</strong> This article series shows how to implement federated GraphQL API using a self-hosted Apollo router. To use the self-hosted Apollo router, you need an <a href="https://new.apollographql.com/pricing">Apollo enterprise plan</a>.</blockquote><p>Then create a separate file named router.yaml file. This is used to configure the Apollo Router. Following is a sample configuration file:</p><pre>sandbox:<br>  enabled: true<br><br>homepage:<br>  enabled: false<br><br>supergraph:<br>  introspection: true<br><br>include_subgraph_errors:<br>  all: true # Propagate errors from all subgraphs<br><br>cors:<br>  origins:<br>    - http://localhost:4000<br>    - https://studio.apollographql.com</pre><p>Refer to the <a href="https://www.apollographql.com/docs/router/configuration/overview/">Apollo Router documentation</a> for more information about configuring the router.</p><p>Now we can run the router. You need the APOLLO_KEY and the APOLLO_GRAPH_REF Execute the following command to run the Apollo Router:</p><pre>APOLLO_KEY=&lt;Your Apollo Key&gt; APOLLO_GRAPH_REF=&lt;Your Apollo Graph Ref&gt; ./router - config router.yaml</pre><p>Once the router is up and running, it will print the router link on the stdout (the default value is http://localhost:4000), so that you can try out your federated supergraph. When you access the link using a browser, it will start an Apollo Sandbox instance. (This is configured using the router.yaml file mentioned above).</p><p>Now use the following GraphQL document to test your federated GraphQL API:</p><pre>query ExampleQuery {<br>  products {<br>    id<br>    name<br>  }<br>  reviews {<br>    id<br>    rating<br>  }<br>  users {<br>    id<br>    name<br>  }<br>}</pre><p>This will return the following response if everything is running correctly.</p><pre>{<br>  &quot;data&quot;: {<br>    &quot;products&quot;: [<br>      {<br>        &quot;id&quot;: &quot;product_0&quot;,<br>        &quot;name&quot;: &quot;Shoes&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;product_1&quot;,<br>        &quot;name&quot;: &quot;T-shirt&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;product_2&quot;,<br>        &quot;name&quot;: &quot;Pants&quot;<br>      }<br>    ],<br>    &quot;reviews&quot;: [<br>      {<br>        &quot;id&quot;: &quot;review_0&quot;,<br>        &quot;rating&quot;: 4<br>      },<br>      {<br>        &quot;id&quot;: &quot;review_1&quot;,<br>        &quot;rating&quot;: 3<br>      },<br>      {<br>        &quot;id&quot;: &quot;review_2&quot;,<br>        &quot;rating&quot;: 1<br>      },<br>      {<br>        &quot;id&quot;: &quot;review_3&quot;,<br>        &quot;rating&quot;: 4<br>      }<br>    ],<br>    &quot;users&quot;: [<br>      {<br>        &quot;id&quot;: &quot;1&quot;,<br>        &quot;name&quot;: &quot;Alice&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;2&quot;,<br>        &quot;name&quot;: &quot;Bob&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;3&quot;,<br>        &quot;name&quot;: &quot;Charlie&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;4&quot;,<br>        &quot;name&quot;: &quot;Dave&quot;<br>      },<br>      {<br>        &quot;id&quot;: &quot;5&quot;,<br>        &quot;name&quot;: &quot;Eve&quot;<br>      }<br>    ]<br>  }<br>}</pre><p>Congratulations! Now you have a working federated supergraph. Let’s check how to add Entity types to this federated supergraph in the next part of this article series.</p><blockquote>Continue reading on <a href="https://thisaru.medium.com/graphql-federation-with-ballerina-and-apollo-part-ii-d05ee4fcd796?source=friends_link&amp;sk=ecc2cc5979be3c560a040281123485a4">Part II</a> of this article.</blockquote><p>Visit my blog: <a href="https://thisaru.me/thoughts/graphql-federation-with-ballerina-part-i/">https://thisaru.me/thoughts</a></p><blockquote>Ballerina is an open-source project. We welcome any kind of contributions to the Ballerina platform, including <a href="https://github.com/ballerina-platform/module-ballerina-graphql"><strong><em>starring</em></strong> <strong><em>on GitHub</em></strong>.</a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=680f5aeae131" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/graphql-federation-with-ballerina-and-apollo-part-i-680f5aeae131">GraphQL Federation with Ballerina and Apollo — Part I</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[GraphQL Subscriptions with Apache Kafka in Ballerina]]></title>
            <link>https://medium.com/ballerina-techblog/graphql-subscriptions-with-apache-kafka-in-ballerina-b3c296d333cd?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/b3c296d333cd</guid>
            <category><![CDATA[graphql]]></category>
            <category><![CDATA[subscription]]></category>
            <category><![CDATA[graphql-subscriptions]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[kafka]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Mon, 06 Feb 2023 11:45:06 GMT</pubDate>
            <atom:updated>2025-06-28T16:27:30.167Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cXSjcKSqPyoOgQpn7EL18w.png" /><figcaption>Diagram of News Alert System with GraphQL Subscriptions with Kafka in Ballerina</figcaption></figure><h3>Introduction</h3><p>This guide is to show how to implement GraphQL subscriptions with Apache Kafka using the Ballerina programming language. In this example, a news alert system is designed. It has the following features.</p><ul><li>There are predefined news agencies.</li><li>Publishers can register with a news agency.</li><li>Subscribers can register to the news alert system.</li><li>Subscribers can subscribe to a particular news agency.</li><li>When a publisher from a news agency publishes news, all the subscribers of that news agency receive the news update in real-time.</li></ul><h3>Design</h3><p>The news alert system uses a GraphQL API. Internally, GraphQL uses Apache Kafka for handling real-time events. The system is implemented using Ballerina. Above image shows the high-level architecture of the news alert system.</p><h4>GraphQL API</h4><p>The GraphQL API connects the Data Store, Kafka broker, Publishers, and Subscribers. Following is the schema of the GraphQL service. This will be auto-generated by the Ballerina GraphQL engine, once the Ballerina GraphQL service is written.</p><pre>type Query {<br>    users: [User!]!<br>    publishers: [Publisher!]!<br>}<br><br>type Mutation {<br>    publish(update: NewsUpdate!): News!<br>    registerUser(newUser: NewUser!): User!<br>    registerPublisher(newPublisher: NewPublisher!): Publisher!<br>}<br><br>type Subscription {<br>    news(userId: String!, agency: Agency!): News!<br>}<br><br>type NewUser {<br>    name: String!<br>    age: Int!<br>}<br><br>type NewPublisher {<br>    name: String!<br>    agency: Agency!<br>}<br><br>type User {<br>    id: String!<br>    name: String!<br>    age: Int!<br>}<br><br>type Publisher {<br>    id: String!<br>    name: String!<br>    agency: Agency!<br>}<br><br>type NewsUpdate {<br>    headline: String!<br>    brief: String!<br>    content: String!<br>    publisherId: String!<br>}<br><br>type News {<br>    id: String!<br>    headline: String!<br>    brief: String!<br>    content: String!<br>    publisher: Publisher!<br>}<br><br>enum Agency {<br>    CBC<br>    BNN<br>    FIRST_NEWS<br>}</pre><blockquote>Note: For the sake of simplicity of this example, the news agencies are pre-defined.</blockquote><p><strong>Query Type</strong></p><p>Query type has two fields.</p><ul><li>The users Field<br>can be used to retrieve the information about the existing users of the news alert system. This will return an array of User type.</li><li>The publishers Field <br>Can be used to retrieve the information about the existing news publishers registered to the news alert system. This will return an array of Publisher type.</li></ul><p><strong>Mutation Type</strong></p><p>Mutation type has three fields.</p><ul><li>The registerUser Field Can be used to register new users for the news alert system. It takes a single argument newUser that is of type NewUser. It contains the name and the age of the user. This will return a value of User type, which includes the user information along with the user ID created for for the user after a successful registration. This ID then can be used to subscribe to different news agencies.</li><li>The registerPublisher Field Can be used to register new publishers for the news alert system. It takes a single argument, newPublisher that is of type NewPublisher. It contains the name, area, and the agency of the publisher. This will return a value of Publisher type, which will include the publisher information along with the publisher ID created for the publisher after a successful registration. This ID can then be used to publish news updates under the registered agency.</li><li>The publish Field Can be used to publish a news update. It takes a single argument update that is of type NewsUpdate. It contains the headline, brief, content, and publisherId. This will return NewsRecord value, which contains the information about the published news update along with the ID generated for the published news item.</li></ul><p><strong>Subscription Type</strong></p><p>Subscription type has a single field.</p><ul><li>The news Field Can be used to subscribe to a particular news agency. It takes two arguments, userId, which is generated when the user is created, and the agency, to which the user needs to subscribe. When a user subscribed to a news agency, the GraphQL API will continuously sends the news updates from that agency whenever a new update is published.</li></ul><h4>Data Store</h4><p>The data store is used to store information about the publishers and the subscribers. There are two tables in the data store.</p><ul><li>User Table The user table is used to store information about the subscribers of the news alert system. When a user is registered through the GraphQL API, a new entry is added to the user table, storing the userId, name, and age.</li><li>Publisher Table The publisher table is used to store information about the publishers of the news alert system. When a publisher is registered through the news alert API, a new entry is added to the publisher table, storing the publisherId, name, area, and the agency.</li></ul><blockquote><strong>Note:</strong> For the sake of simplicity of the example, in-memory Ballerina tables are used as the data stores.</blockquote><h4>Kafka</h4><p>Apache Kafka is used for handling real-time events in the news alert system.</p><ul><li>Each news agency has a separate Kafka topic.</li><li>When a publisher from a particular news agency publishes a piece of news through the GraphQL API, that news is published to the corresponding Kafka topic.</li><li>When a subscriber subscribes to a particular news agency using GraphQL subscription, a new Kafka consumer is created for the topic and all the events published to that topic is dispatched to the user through GraphQL API.</li></ul><h3>Prerequisites</h3><ul><li>Download and install <a href="https://ballerina.io/downloads">Ballerina Distribution</a></li><li>Download <a href="https://kafka.apache.org/downloads">Apache Kafka</a></li><li>VS Code with <a href="https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina">Ballerina plugin</a> (Recommended) or any other IDE</li></ul><h3>Implementation</h3><h4>Creating a Project</h4><p>To create a new Ballerina project, execute the following command in a terminal. (Make sure that the Ballerina is installed correctly). The Ballerina service template can be used to create the Ballerina project.</p><pre>bal new news_alerts --template service</pre><p>This will create a new directory named news_alerts and in will contain the following files.</p><pre>news_alert<br>├── Ballerina.toml<br>├── service.bal<br>└── tests<br>    └── service_test.bal</pre><blockquote><strong>Note:</strong> To reduce the complexity, this example does not intend to describe the testing of the project.</blockquote><h4>Defining Types</h4><p>First, the Ballerina types that are used in the GraphQL service are defined. These types can be found in the types.bal file.</p><p><strong>Input Types</strong></p><p>In Ballerina GraphQL, record types are used to represent GraphQL input objects. There are three input object types are defined in the GraphQL schema: NewUser, NewPublisher, and NewsUpdate. Following record type definitions are used to represent these input object types.</p><pre>type NewUser record {|<br>    string name;<br>    int age;<br>|};<br><br>type NewPublisher record {|<br>    string name;<br>    string area;<br>    Agency agency;<br>|};<br><br>type NewsUpdate record {|<br>    string headline;<br>    string brief;<br>    string content;<br>    string publisherId;<br>|};</pre><p><strong>Enums</strong></p><p>The predefined news agencies are defined using an enum, Agency. Ballerina enums can be used to define GraphQL enums. Following is the enum definition.</p><pre>enum Agency {<br>    FIRST_NEWS,<br>    BNN,<br>    CBC<br>}</pre><p><strong>Output Objects</strong></p><p>In Ballerina, a GraphQL output object can be defined using either a Ballerina service type, or a Ballerina record type. If an object does not have fields with input arguments and does not need calculations or processing to resolve the field value, a record type can be used. Otherwise, a service type can be used.</p><p>Since the User and the Publisher object types do not have any field with inputs and they do not need any calculation/processing to resolve the field value, record types can be used to define these types. Note that the Ballerina type inclusion is used to copy the similar fields from the previously defined record types. Only the additional id field is added.</p><pre>type User record {|<br>    readonly string id;<br>    *NewUser;<br>|};<br><br>type Publisher record {|<br>    readonly string id;<br>    *NewPublisher;<br>|};</pre><p>But the News type has some processing to do since it has a publisher field that needs to be loaded from a separate table. Therefore, a service type is used to represent the News type. A NewsRecord type is defined to initialize the News type. The resource methods of the service type are used to represent GraphQL object fields.</p><pre>type NewsRecord readonly &amp; record {|<br>    readonly string id;<br>    *NewsUpdate;<br>|};<br><br>isolated service class News {<br>    private final readonly &amp; NewsRecord newsRecord;<br><br>    isolated function init(NewsRecord newsRecord) {<br>        self.newsRecord = newsRecord;<br>    }<br><br>    isolated resource function get id() returns string =&gt; self.newsRecord.id;<br><br>    isolated resource function get headline() returns string =&gt; self.newsRecord.headline;<br><br>    isolated resource function get brief() returns string =&gt; self.newsRecord.brief;<br><br>    isolated resource function get content() returns string =&gt; self.newsRecord.content;<br><br>    isolated resource function get publisher() returns Publisher {<br>        lock {<br>            return publisherTable.get(self.newsRecord.publisherId);<br>        }<br>    }<br>}</pre><p>Now all the required types are defined.</p><h4>Defining Data Sources</h4><p>To keep this example simple, Ballerina in-memory tables are used. Ballerina has a built-in table type that suites this scenario. Note that these can be easily converted to a relational database.</p><p>Following are the definitions of the two tables that are used in this example to store the users and the publishers. These tables are defined in the datasource.bal file.</p><pre>isolated table&lt;User&gt; key(id) userTable = table [];<br><br>isolated table&lt;Publisher&gt; key(id) publisherTable = table [];</pre><h4>Implementing Kafka Connectivity</h4><p>Ballerina has a ballerinax/kafka package, which is a part of the Ballerina extended library, that is used to communicate with a Kafka broker. It is used in this example.</p><blockquote><strong>Note:</strong> To use ballerinax/kafka package, it should be pulled from the Ballerina central. To pull the package, execute the following command in a terminal.</blockquote><blockquote><em>bal pull ballerinax/kafka</em></blockquote><blockquote>Alternatively, the Ballerina VS Code plugin can be used to pull the package via code actions.</blockquote><p>All the Kafka-related code in this example is found in kafka_utils.bal file.</p><p>There are two main functionalities that are related to Kafka in this example.</p><ul><li>When a publisher publishes a news update, that update should be published to a Kafka topic.</li><li>When a user subscribes to an agency, a new Kafka consumer should be created for consuming all the updates from that topic as a Ballerina stream type which used to send/receive streams of data in Ballerina. In Ballerina GraphQL, a subscription operation must return a stream type in order to send data continuously to the subscribers.</li></ul><p><strong>Producing News</strong></p><p>To produce a news update to a Kafka topic, a Kafka producer is needed. Following code shows how to define a Kafka consumer and how to produce a news update to the Kafka topic. In this example, the default Kafka broker is used, therefore the kafka:DEFAULT_URL is used as the Kafka broker URL.</p><p>The produceNews function takes a NewsUpdate record (that was defined earlier) and generates an ID for the update, then publishes it to the Kafka topic related to the agency.</p><p>The getAgency function is used to retrieve the agency of the publisher. It will return an error if the publisher is not found.</p><pre>import ballerina/uuid;<br><br>isolated function produceNews(NewsUpdate newsUpdate) returns NewsRecord|error {<br>    kafka:Producer producer = check new (kafka:DEFAULT_URL);<br>    string id = uuid:createType1AsString();<br>    Agency agency = check getAgency(newsUpdate.publisherId);<br>    NewsRecord news = {id: id, ...newsUpdate};<br>    check producer-&gt;send({topic: agency, key: id, value: news});<br>    return news;<br>}<br><br>isolated function getAgency(string publisherId) returns Agency|error {<br>    lock {<br>        if publisherTable.hasKey(publisherId) {<br>            return publisherTable.get(publisherId).agency;<br>        }<br>    }<br>    return error(&quot;Publisher not found&quot;);<br>}</pre><blockquote><strong>Note:</strong> The ballerina/uuid package is used to generate unique IDs. Since it is a Ballerina standard library package, no additional work is needed for using it.</blockquote><p><strong>Consuming News</strong></p><p>News consuming should be done in the following manner.</p><ul><li>If a user requested to subscribe to a particular news agency, a new Kafka consumer with a new user group should be created, in order to make sure all the users receive all the news published to a particular topic.</li><li>Since publishing news is a continuous process, and the GraphQL subscription needs to return a Ballerina stream, all the consumed news should be added to a stream.</li></ul><p>To do this, a Ballerina StreamGenerator object is used. Each time a StreamGenerator is created, a new Kafka consumer is created for retrieve messages from the Kafka topic. A StreamGenerator must define a next method that will return a record in which the retrieved news is stored in the value field. It uses a configurable variable POLL_INTERVAL for polling the Kafka records from the server, and after polling, returns the news update or logs an error/warning if polling fails.</p><p>Following code snippet defines the StreamGenerator object.</p><pre>configurable decimal POLL_INTERVAL = 100.0;<br><br>isolated class NewsStream {<br>    private final string consumerGroup;<br>    private final Agency agency;<br>    private final kafka:Consumer consumer;<br><br>    isolated function init(string consumerGroup, Agency agency) returns error? {<br>        self.consumerGroup = consumerGroup;<br>        self.agency = agency;<br>        kafka:ConsumerConfiguration consumerConfiguration = {<br>            groupId: consumerGroup,<br>            offsetReset: &quot;earliest&quot;,<br>            topics: agency,<br>            maxPollRecords: 1 // Limit the number of records to be polled at a time<br>        };<br>        self.consumer = check new (kafka:DEFAULT_URL, consumerConfiguration);<br>    }<br><br>    public isolated function next() returns record {|News value;|}? {<br>        NewsRecord[]|error newsRecords = self.consumer-&gt;pollPayload(POLL_INTERVAL);<br>        if newsRecords is error {<br>            // Log the error with the consumer group id and return nil<br>            log:printError(&quot;Failed to retrieve data from the Kafka server&quot;, newsRecords, id = self.consumerGroup);<br>            return;<br>        }<br>        if newsRecords.length() &lt; 1 {<br>            // Log the warning with the consumer group id and return nil. This will end the subscription as returning<br>            // nil will be interpreted as the end of the stream.<br>            log:printWarn(string `No news available in &quot;${self.agency}&quot;`, id = self.consumerGroup);<br>            return;<br>        }<br>        return {value: new (newsRecords[0])};<br>    }<br>}</pre><h4>Implementing the GraphQL API</h4><p>Now the GraphQL API can be implemented since all the other types/methods are defined. To define a GraphQL service, the ballerina/graphql package is used. It is a part of the Ballerina standard library. Therefore, no additional work is needed.</p><p>Following code snippet shows how to define a GraphQL service in Ballerina. Remove the code in the service.bal and use this code to implement the GraphQL service.</p><p>Ballerina GraphQL comes with a built-in GraphiQL client for testing purposes, which can be enabled through graphql:ServiceConfig. It is enabled via a configurable variable ENABLE_GRAPHIQL. Value of this variable is provided in the Config.toml file in the project.</p><pre>import ballerina/graphql;<br><br>configurable boolean ENABLE_GRAPHIQL = ?;<br><br>@graphql:ServiceConfig {<br>    graphiql: {<br>        enabled: ENABLE_GRAPHIQL<br>    }<br>}<br>service /news_alert on new graphql:Listener(9090) {<br>    // Implement the resource and remote methods here<br>}</pre><p><strong>Query Fields</strong></p><p>As per the GraphQL schema, there are two fields in the Query type. In Ballerina, resource methods with get accessor are used to represent the fields of the Query type. Following are the definitions of the resource methods that represent the fields of the Query type. Add these methods inside the GraphQL service defined previously.</p><pre>resource function get users() returns readonly &amp; User[] {<br>    lock {<br>        return from User user in userTable<br>            select user.cloneReadOnly();<br>    }<br>}<br><br>resource function get publishers() returns readonly &amp; Publisher[] {<br>    lock {<br>        return from Publisher publisher in publisherTable<br>            select publisher.cloneReadOnly();<br>    }<br>}</pre><h4>Mutation Fields</h4><p>As per the GraphQL schema, there are three fields in the Mutation type. In Ballerina, remote methods are used to represent the fields of the Mutation type. Following are the definitions of the remote methods that represents the fields of the Mutation method. Add these methods inside the service defined previously.</p><pre>remote function publish(NewsUpdate &amp; readonly update) returns NewsRecord|error {<br>    lock {<br>        if publisherTable.hasKey(update.publisherId) {<br>            return produceNews(update).cloneReadOnly();<br>        }<br>    }<br>    return error(&quot;Invalid publisher&quot;);<br>}<br><br>remote function registerUser(NewUser newUser) returns User {<br>    string id = uuid:createType1AsString();<br>    lock {<br>        User user = {id: id, ...newUser.cloneReadOnly()};<br>        userTable.put(user);<br>        return user.cloneReadOnly();<br>    }<br>}<br><br>remote function registerPublisher(NewPublisher newPublisher) returns Publisher {<br>    string id = uuid:createType1AsString();<br>    lock {<br>        Publisher publisher = {id: id, ...newPublisher.cloneReadOnly()};<br>        publisherTable.put(publisher);<br>        return publisher.cloneReadOnly();<br>    }<br>}</pre><blockquote><strong>Note:</strong> Ballerina locks are used to access the tables to make this concurrency-safe, enabling the methods to run parallelly.</blockquote><p><strong>Subscription Fields</strong></p><p>As per the GraphQL schema, there is a single field in the Subscription type. In Ballerina, resource methods with subscribe accessor are used to represent the fields of the Subscription type. Following is the definition of the resource methods that represent the fields of the Query type. Add this method inside the GraphQL service defined previously.</p><p>The previously created StreamGenerator type is used to return a stream from this method.</p><pre>resource function subscribe news(string userId, Agency agency) returns stream&lt;News&gt;|error {<br>    stream&lt;News&gt; newsStream;<br>    lock {<br>        if userTable.hasKey(userId) {<br>            NewsStream newsStreamGenerator = check new (userId, agency);<br>            newsStream = new (newsStreamGenerator);<br>        } else {<br>            return error(&quot;User not registered&quot;);<br>        }<br>    }<br>    return newsStream;<br>}</pre><h3>Running the Service</h3><ul><li>First, <a href="https://kafka.apache.org/quickstart">run the Kafka broker</a> in a terminal.</li><li>Then in another terminal, run the Ballerina project. To run the project, execute the following command inside the project directory.<br>bal run</li><li>After running the project, a GraphiQL client will be running on localhost:9090/graphiql. Use a web browser to access it.</li><li>Using the browser, register a new user using the following document.</li></ul><pre>mutation {<br>  registerUser(newUser: {name: &quot;John Doe&quot;, age: 30}) {<br>      id<br>  }<br>}</pre><ul><li>This will return a response similar to the following.</li></ul><pre>{<br>  &quot;data&quot;: {<br>    &quot;registerUser&quot;: {<br>      &quot;id&quot;: &quot;01eda2b9-1d25-1816-97f8-c39f3cf1e39e&quot;<br>    }<br>  }<br>}</pre><ul><li>Keep the user ID received from the GraphQL service for future usage.</li><li>Then register a new publisher using the following document.</li></ul><pre>mutation {<br>  registerPublisher(<br>      newPublisher: {<br>          name: &quot;Jane Doe&quot;<br>          agency: CBC<br>      }<br>  ) {<br>    id<br>  }<br>}</pre><ul><li>This will return a response similar to the following.</li></ul><pre>{<br>  &quot;data&quot;: {<br>    &quot;registerPublisher&quot;: {<br>      &quot;id&quot;: &quot;01eda2b9-6970-1c10-8f79-534f8bf7ae46&quot;<br>    }<br>  }<br>}</pre><ul><li>Keep the publisher ID received from the GraphQL service for the future usage.</li><li>Now subscribe to a news agency using the following document.</li></ul><pre>subscription {<br>  news(userId: &quot;01eda2b9-1d25-1816-97f8-c39f3cf1e39e&quot;, agency: CBC) {<br>    headline<br>    publisher {<br>      name<br>    }<br>  }<br>}</pre><ul><li>In a separate browser tab, use the following document to publish a news.</li></ul><pre>mutation {<br>  publish(<br>      update: {<br>          headline: &quot;Hello&quot;<br>          brief: &quot;Hola&quot;<br>          content: &quot;Hello world!&quot;<br>          publisherId: &quot;01eda2b9-6970-1c10-8f79-534f8bf7ae46&quot;<br>      }<br>  ) {<br>    id<br>  }<br>}</pre><ul><li>Now, check the browser tab that used to subscribe to the news agency. It will show the published news message similar to this.</li></ul><pre>{<br>  &quot;data&quot;: {<br>    &quot;news&quot;: {<br>      &quot;headline&quot;: &quot;Hello&quot;,<br>      &quot;publisher&quot;: {<br>        &quot;name&quot;: &quot;Jane Doe&quot;<br>      }<br>    }<br>  }<br>}</pre><p>This sample codes in this guide may miss some parts, such as API documentation for the GraphQL API. Those can be found in the <a href="https://github.com/ballerina-platform/module-ballerina-graphql/tree/master/examples/news_alerts">original repository</a>. Please provide feedback, questions, issues related to the Ballerina GraphQL package in <a href="https://github.com/ballerina-platform/ballerina-standard-library">Ballerina Standard Library</a> repository.</p><p>Visit my blog: <a href="https://thisaru.me/thoughts/graphql-federation-with-ballerina-part-i/">https://thisaru.me/thoughts</a></p><p>Ballerina is an open-source project. We value your feedback. <a href="https://github.com/ballerina-platform/module-ballerina-graphql">Stars</a> are always welcome.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b3c296d333cd" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/graphql-subscriptions-with-apache-kafka-in-ballerina-b3c296d333cd">GraphQL Subscriptions with Apache Kafka in Ballerina</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[REST is History, Let’s Do GraphQL (with Ballerina)]]></title>
            <link>https://medium.com/ballerina-techblog/rest-is-history-lets-do-graphql-with-ballerina-dce7510b61e8?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/dce7510b61e8</guid>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[graphql-vs-rest]]></category>
            <category><![CDATA[graphql]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[integration]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 29 Jun 2021 11:05:31 GMT</pubDate>
            <atom:updated>2025-06-28T16:28:30.323Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This article explains how to convert a REST API to a GraphQL API using Ballerina. <br>Ballerina is an open source language mainly focused on network and cloud native programming. If you haven’t installed Ballerina yet, you can <a href="https://ballerina.io/downloads/">download it from here</a>. You can <a href="https://ballerina.io/learn/">Learn Ballerina</a> easily too!</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zm95u6OhP0XKFIqf6XZYuw.png" /></figure><p>I am not wrong if I state that the REST APIs have been dominating the computing world for a long time now. They are in mobile applications, web applications, embedded systems, etc. We see REST APIs everywhere!</p><p>Even though the REST APIs have a lot of great features, and they have been a great asset when it becomes to integrations, there are some drawbacks.</p><p>To show one of these drawbacks, let’s consider the <a href="https://www.weatherapi.com/">weatherapi.com</a>, a free weather API. It provides a REST API to retrieve weather information of a given location.</p><blockquote>You need an API key to retrieve weather data from the weatherapi.com. An API key can be created for free from the <a href="https://www.weatherapi.com/">weatherapi.com</a>.</blockquote><p>Say we have a mobile app, where we want to get the current temperature and the time of a provided city. To get these data we have to send a GET request to the following endpoint:</p><pre>http://api.weatherapi.com/v1/current.json?key=&lt;API_KEY&gt;&amp;q=&lt;LOCATION&gt;</pre><p>This will return a JSON object, similar to the following:</p><pre>{<br>    &quot;location&quot;: {<br>        &quot;name&quot;: &quot;Colombo&quot;,<br>        &quot;region&quot;: &quot;Western&quot;,<br>        &quot;country&quot;: &quot;Sri Lanka&quot;,<br>        &quot;lat&quot;: 6.93,<br>        &quot;lon&quot;: 79.85,<br>        &quot;tz_id&quot;: &quot;Asia/Colombo&quot;,<br>        &quot;localtime_epoch&quot;: 1624954019,<br>        &quot;localtime&quot;: &quot;2021-06-29 13:36&quot;<br>    },<br>    &quot;current&quot;: {<br>        &quot;last_updated_epoch&quot;: 1624950000,<br>        &quot;last_updated&quot;: &quot;2021-06-29 12:30&quot;,<br>        &quot;temp_c&quot;: 31.0,<br>        &quot;temp_f&quot;: 87.8,<br>        &quot;is_day&quot;: 1,<br>        &quot;condition&quot;: {<br>            &quot;text&quot;: &quot;Partly cloudy&quot;,<br>            &quot;icon&quot;: &quot;//cdn.weatherapi.com/weather/64x64/day/116.png&quot;,<br>            &quot;code&quot;: 1003<br>        },<br>        &quot;wind_mph&quot;: 12.5,<br>        &quot;wind_kph&quot;: 20.2,<br>        &quot;wind_degree&quot;: 220,<br>        &quot;wind_dir&quot;: &quot;SW&quot;,<br>        &quot;pressure_mb&quot;: 1008.0,<br>        &quot;pressure_in&quot;: 30.2,<br>        &quot;precip_mm&quot;: 0.9,<br>        &quot;precip_in&quot;: 0.04,<br>        &quot;humidity&quot;: 75,<br>        &quot;cloud&quot;: 75,<br>        &quot;feelslike_c&quot;: 37.5,<br>        &quot;feelslike_f&quot;: 99.6,<br>        &quot;vis_km&quot;: 10.0,<br>        &quot;vis_miles&quot;: 6.0,<br>        &quot;uv&quot;: 6.0,<br>        &quot;gust_mph&quot;: 13.4,<br>        &quot;gust_kph&quot;: 21.6<br>    }<br>}</pre><p>Then we have to process this (large?) JSON object, and get the current temperature and the time of the location. But do we need all these other information? No!</p><p>If we look closely, <strong>we have retrieved 33 fields</strong> (ignoring the intermediate levels), <strong>where we actually need just 2 fields</strong>! Consider the amount of network bandwidth and memory we are wasting (which is crucial when it comes to mobile apps).</p><blockquote>This is the problem called over-fetching in REST APIs. We have to fetch data we do not need, in order to retrieve the data we need.</blockquote><blockquote>There’s another major issue called under-fetching, which is the opposite of over-fetching, where we have to call multiple APIs to get the data, because one API does not provide all the information you need. This article will not discuss that here, which will be a separate article.</blockquote><p>GraphQL overcomes this over-fetching issue by defining the data in a structured manner, where users can request exactly what they want, and the service will serve exactly what they asked.</p><p>But, what about the existing REST APIs? Can we migrate all these to GraphQL? The answer is YES!</p><p>This is where the Ballerina GraphQL becomes handy. In this article I am going to show how to convert this weather REST API to a GraphQL API using Ballerina.</p><p>Let’s go back to the start. We can retrieve the data from the weather API using Ballerina HTTP module. Check the following code:</p><pre>import ballerina/http;</pre><pre>http:Client httpClient = check new(&quot;http://api.weatherapi.com/v1&quot;);<br>configurable string API_KEY = ?;<br>const CURRENT_WEATHER_ENDPOINT = &quot;/current.json&quot;;</pre><pre>function getCurrentWeather(string city) {<br>    string query = string`?key=${API_KEY}&amp;q=${city}`;<br>    return httpClient-&gt;get(CURRENT_WEATHER_ENDPOINT + query);<br>}</pre><blockquote>The API_KEY here is defined as a configurable variable, for which the actual value can be provided when the program is running. To learn more about the configurable variables, visit <a href="https://ballerina.io/learn/user-guide/configurability/defining-configurable-variables/">Ballerina Learn pages</a>.</blockquote><p>Here, the data json object (json is a built in type in Ballerina, if you’re wondering) contains all the information we need. Actually, it contains more than the information we actually need. (That’s the problem we are going to solve, remember?). The JSON object returned here as the data is similar to the one shown above.</p><p>Now we are going to write a GraphQL service using Ballerina, to serve these information. We can use the above HTTP client code for this.</p><p>As mentioned above, GraphQL defines structured data types to serve. We are going to define these types in Ballerina first.</p><pre>type WeatherResponse record {|<br>    Weather current;<br>    Location location;<br>|};</pre><pre>type Weather record {<br>    float temp_c;<br>};</pre><pre>type Location record {<br>    string localtime;<br>};</pre><p>Check how the record types are defined here, matching with the above JSON object. In the response, we have two main fields, current and location. We create a WeatherResponse record to match that. The location field is of type Location, and the current field is of type Weather. Since these two are the only fields in the top-level JSON object, it is defined as a closed record.</p><p>For the Weather and Location records, we do not need all the fields inside them (for now). Therefore, only the required fields are defined here. (Note the field names are exactly the same as the field names in the JSON object, which is important).</p><p>Now we can update the previous HTTP client code as follows:</p><pre>import ballerina/http;</pre><pre>http:Client httpClient = check new(&quot;http://api.weatherapi.com/v1&quot;);<br>configurable string API_KEY = ?;<br>const CURRENT_WEATHER_ENDPOINT = &quot;/current.json&quot;;</pre><pre>function getCurrentWeather(string city) returns json|error {<br>    string query = string`?key=${API_KEY}&amp;q=${city}`;<br>    return httpClient-&gt;get(CURRENT_WEATHER_ENDPOINT + query);<br>}</pre><p>This new function getCurrentWeather is returning the JSON object of the current weather for a given location, or an error if an error occurred while calling the get method of the Ballerina HTTP client.</p><p>Now we can write a GraphQL service to return aWeatherResponse object.</p><pre>import ballerina/graphql;</pre><pre>service /weather on new graphql:Listener(4000) {<br>    resource function get weather(string city) returns WeatherResponse|error {<br>        json weatherResponseJson = check getCurrentWeather(city);<br>        return weatherResponseJson.cloneWithType();<br>    }<br>}</pre><p>That’s it! Now we are serving these details as a GraphQL service! This service can be used as a gateway to access to the weather API through GraphQL.</p><p>The following is the complete code (in a single ballerina file) for the example this article explained.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/34eb89e71969e430b4ffb76004316068/href">https://medium.com/media/34eb89e71969e430b4ffb76004316068/href</a></iframe><p>You can try this out by running this using the following bal commnd</p><pre>bal run weather_graphql.bal -- -CAPI_KEY=&lt;YOUR_WEATHER_API_KEY&gt;</pre><p>After running, we can test this out using a GraphQL client such as <a href="https://github.com/graphql/graphql-playground">GraphQL PlayGround</a> or <a href="https://altair.sirmuel.design/">Altair GraphQL Client</a>, or just by a simple cURL command like below:</p><pre>curl -X POST -H &quot;Content-type: application/json&quot; -d &#39;{ &quot;query&quot;: &quot;{ weather(city: \&quot;colombo\&quot;) { current { temp_c } location { localtime } } }&quot; }&#39; &#39;<a href="http://localhost:8080/weather&#39;">http://localhost:4000/weather&#39;</a></pre><p>In this cURL command, we send the request with the following GraphQL document</p><pre>{<br>    weather(city: &quot;colombo&quot;) {<br>        current {<br>            temp_c<br>        }<br>        location {<br>            localtime<br>        }<br>    }<br>}</pre><p>The response from the server is the following:</p><pre>{<br>  &quot;data&quot;: {<br>    &quot;weather&quot;: {<br>      &quot;current&quot;: {<br>        &quot;temp_c&quot;: 30<br>      },<br>      &quot;location&quot;: {<br>        &quot;localtime&quot;: &quot;2021-06-29 15:10&quot;<br>      }<br>    }<br>  }<br>}</pre><p>Now there’s only the information we actually requested, nothing more, nothing less.</p><p><a href="https://github.com/ThisaruGuruge/weather-rest-api-to-graphql">This GitHub repository</a> contains a complete ballerina package example for converting a REST API to a GraphQL API.</p><p>As the Ballerina language, the Ballerina GraphQL module too is an open source project.</p><p>Visit my blog: <a href="https://thisaru.me/thoughts/graphql-federation-with-ballerina-part-i/">https://thisaru.me/thoughts</a></p><p>Feel free to contribute by reporting issues, requesting new features, or even sending pull requests. GitHub stars are always welcome :)<br><a href="https://github.com/ballerina-platform/module-ballerina-graphql">https://github.com/ballerina-platform/module-ballerina-graphql</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dce7510b61e8" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/rest-is-history-lets-do-graphql-with-ballerina-dce7510b61e8">REST is History, Let’s Do GraphQL (with Ballerina)</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[TENET කියවමු]]></title>
            <link>https://thisaru.medium.com/tenet-%E0%B6%9A%E0%B7%92%E0%B6%BA%E0%B7%80%E0%B6%B8%E0%B7%94-3c1d543d8125?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/3c1d543d8125</guid>
            <category><![CDATA[sinhala]]></category>
            <category><![CDATA[tenet-review]]></category>
            <category><![CDATA[tenet-2020]]></category>
            <category><![CDATA[sinhala-movie-review]]></category>
            <category><![CDATA[movie-review]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Fri, 25 Dec 2020 16:48:23 GMT</pubDate>
            <atom:updated>2025-06-21T05:59:38.765Z</atom:updated>
            <content:encoded><![CDATA[<p>ක්‍රිස්ටෝෆර් නෝලන් කියන්නේ “අමුතු” ජාතියේ “වැඩ” කරන අධ්‍යක්ෂ්‍යකවරයෙක් බව සිනමා රසිකයන්ට අළුත් දෙයක් නෙවෙයි. නෝලන්ගේ අළුත් ම “වැඩේ” තමයි TENET.</p><p>නෝලන් ගේ ගොඩක් කතා වගේ ම, මේකත් එක පාර බැලුවට හරියට ම තේරෙන්නේ නැති, ටිකක් සංකීර්ණ කතාවක්. මේ නොතේරීමට කතාවේ සංකීර්ණ බව වගේ ම, නොපැහැදිලි දෙබස්, මහ හයියෙන් ඇහෙන පසුබිම් සංගීතය වගෙ කාරණාත් බලපානවා කිව්වොත් වැරදි නෑ. විශේෂයෙන් ම සිනමා ශාලාවක TENET නරඹපු කෙනෙක් ට මේක එක පාරින් තේරුම් ගන්න එක සෑහෙන අමාරු වැඩක්.</p><p>ඒ තාක්ෂණික කාරණා අතෑරලා, කතාවට දිහා බලමු.</p><p>TENET — චිත්‍රපටයේ නම ම ටිකක් අමුතු වැඩක්. මේ වචනය මුල ඉඳලා අගට කියෙව්වත්, අග ඉඳලා මුලට කියෙව්වත් එක ම වචනයක්. අපි මේ වගේ වචන වලට “පැලින්ඩ්‍රෝමයක්” (Palindrome) කියලා කියනවා. “සරළ සිංහලෙන්” කිව්වොත් “උභයදිශා සර්වසම වචනයක්”!</p><p>TENET කියන්නේ SATOR square කියන ඉපැරණි ලතින් ලියැවිල්ලක වර්ගයක එන වචනයක්. මේ SATOR square එකේ තියෙන්නේ පැලින්ඩ්‍රෝම වචන පහක එකතුවක්. ඒ වචන පහ තමයි SATOR, AREPO, TENET, OPERA, ROTAS!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OgU4A0s0V8Qf79KVZtX-aA.jpeg" /><figcaption>පොම්පෙයි නුවරින් හමු වූ ඉපැරණි Sator Square එකක්. ඡායාරූපය: <a href="https://en.wikipedia.org/wiki/Sator_Square#/media/File:Sator_Square_at_Opp%C3%A8de.jpg">Wikipedia</a></figcaption></figure><p>මේ වචන ටික දැක්කම “අම්මටසිරි” මොහොතක් දැනුනේ නැත්තං, ඔබ චිත්‍රපටය හරියට නරඹලා නෑ. එහෙම නම් මෙතනින් එහාට කියවීම පැත්තක තියලා නැවත චිත්‍රපටය නරඹන්න.</p><h3>*Spoiler Alert*</h3><blockquote>TENET — කියන්නේ SATOR square එකේ හරි මැද තියෙන වචනය. ඒ වගේ ම තමයි මේක TEN කියන වචනය දෙපැත්තකින් එකට කරලා ලිවීමක්. චිත්‍රපටයේ අන්තිම සටන – විනාඩි දහය ගානේ කාලය ඉදිරියටත්, ආපස්සටත්, ගමන් කරන කණ්ඩායම් දෙකක් – TEN — NET! මේ වචනයේ ලතින් අර්ථය ගත්තොත්, නොනැසී පවත්වා ගන්නා (Sustain) එහෙමත් නැත්තනම් සියල්ල ම බැඳ තබාගන්නා වගේ තේරුමක් තමයි තියෙන්නේ. චිත්‍රපටයේ හැටියට ලෝකයේ විනාශය නවත්තලා, මේ තත්ත්වයන් එහෙම ම පවත්වා ගන්න සංවිධානය තමයි TENET!</blockquote><p>අනිත් නම් ටික ගත්තොත්, SATOR කියන්නේ චිත්‍රපටයේ ප්‍රධාන දුශ්ඨයා ගේ නම. SATOR කියන ලතින් වචනයේ තේරුම මූලිකයා, අරඹන්නා වගේ තේරුමක්. ඔහු තමයි චිත්‍රපටයේ හැටියට විනාශය ආරම්භ කරන පුද්ගලයා. AREPO, කියන්නේ චිත්‍රපටයේ ප්‍රධාන කාන්තා චරිතය, Kat ව Sator යටතට පත්වෙන්න හේතු වෙන වංචනික චිත්‍රයේ නිර්මාණකරුවා. OPERA එකක් ඇතුලේ තමයි චිත්‍රපටයේ ආරම්භක දර්ශනය තියෙන්නේ. Sator තමන්ගේ ආරක්ශක සංවිධානය විදිහට බඳවා ගන්නේ ROTAS.</p><p>මේ නම් වලින් පවා නෝලන් සෑහෙන ලස්සන “වැඩක්” කරලා තියෙනවා!</p><p>දැන් එතනින් එහාට යමු. කතාව!</p><p>මේකේ සංකල්පය තේරුම් ගන්න නම්, මුලින් පොඩි භෞතික විද්‍යා දැනුමක් අවශ්‍ය ය වෙනවා. එන්ට්‍රොපිය ගැන චිත්‍රපටයේ සෑහෙන කතා කරනවා. මොකද්ද එන්ට්‍රොපිය කියන්නේ? සරළ ව ගත්තොත්, එන්ට්‍රොපිය කියන්නේ යම්කිසි භෞතික පද්ධතියක ව්‍යාකූලත්වය ගැන මිනුමක් කියලා කියන්න පුළුවන්. කිසියම් පද්ධතියක එන්ට්‍රොපිය වැඩි වෙනවා කියන්නේ, ඒ පද්ධතියේ ව්‍යාකූලත්වය, නැත්නම් disorder එක වැඩි වෙනවා කියන එක කියලා සැලකුවාට ප්‍රශ්නයක් නෑ.</p><p>ඊට පස්සේ අපිට දැනගන්න වෙනවා තාපගති විද්‍යාවේ දෙවැනි නියමය (2nd law of Thermodynamics). මේ නියමය විවිධ විදිහට අර්ථ දක්වන්න පුළුවන්. මේ චිත්‍රපටයේ සන්දර්භයට අවශ්‍ය අර්ථයෙන් ගත්තොත්, දෙවැනි නියමයෙන් කියවෙන්නේ යම්කිසි සංවෘත පද්ධතියක් සමතුලිත වෙන්නේ, එහෙම නැත්නම් යම්කිසි සංවෘත පද්ධතියක් ඇතුලේ සිදුවන ක්‍රියාවලීන් සිදුවෙන්නේ, ඒ පද්ධතියේ එන්ට්‍රොපිය උපරිම වන ආකාරයට කියලා.</p><blockquote>මේක තව ටිකක් පැහැදිලි කරගත්තොත්, අපි අත්දකින භෞතික ක්‍රියාවලීන් ශක්ති සංස්ථිති මූලධර්මයට අනුව හැසිරෙනවා. ඒ කියන්නේ යම්කිසි සංවෘත පද්ධතියක ශක්තිය නියතයි, ශක්තිය එක අවස්ථාවක ඉඳලා වෙනත් අවස්ථාවකට පරිවර්ථනය කරන්න පුළුවන්, නමුත් ශක්තිය මැවීම හෝ නැසීම කළ නොහැකි දෙයක්. ඒක එහෙම වුනත් සමහර ක්‍රියාවලීන් අපිට ආපස්සට හැරවීම කරන්න බෑ.</blockquote><blockquote>සරල උදාහරණයක් ගමු. එලිමහනේ තියන අයිස් කැටයක් දියවෙන බව අපි දන්නවා. එතනදි වෙන්නේ බාහිර පරිසරයේ තියෙන ශක්තිය අවශෝශණය කරගෙන අයිස් කැටයේ තියෙන ජල අණු වල උශ්ණත්වය වැඩි වෙන එක. මෙතනදි ශක්තිය පරිසරයෙන් අයිස් කැටයට ලැබෙනවා. නමුත් සම්පූර්ණ පද්ධතියේ ශක්තිය නියතව තියාගෙන, අයිස් කැටයෙන් ඉතිරි වුන ජලයේ ශක්තිය පරිසරයට පිට කරලා, අපිට නැවත අයිස් කැටය හදාගන්න පුළුවන් ද? බෑ. ඒකට හේතුව තමයි දෙවැනි නියමයෙන් පැහැදිලි කරන්නේ. ශක්තිය ගලන්නේ එන්ට්‍රොපිය වැඩි වෙන විදිහට. අයිස් කැටය, අයිස් කැටයක් ලෙස පවතිනවට වඩා, වැඩි උෂ්ණත්වයකට පත් වෙලා, දියවුනා ම තමයි එන්ට්‍රොපිය වැඩි.</blockquote><blockquote>මේ හැසිරීම නිසා ම තාපගති විද්‍යාවේ දෙවැනි නියමය ට අපි “කාලයේ ඊතලය” (Arror of time) කියලා කියනවා. විශ්වය කියන්නේ සංවෘත පද්ධතියක් කියලා හිතුවොත්, ඒ පද්ධතියේ ක්‍රියාවලීන් සිදුවෙන්නේ එන්ට්‍රොපිය වැඩි වෙන දිශාවට. ඒ කියන්නේ කාලය ගතවෙන්නේ එන්ට්‍රොපිය වැඩි වෙන දිශාවට. ඒ නිසා අපි ට හිතන්න පුළුවන් එන්ට්‍රොපිය වැඩි වෙනවා නම් කාලය ඉදිරියට ගමන් කරන බව. එහෙනම් කාලය ආපස්සට යවන්න නම්, එන්ට්‍රොපිය ප්‍රතිවර්ත (invert) කරන්න ඕන! මේක තමයි කතාවේ හරය.</blockquote><p>චිත්‍රපටයේ හැටියට අනාගතයේ ඉන්න විද්‍යාඥවරියක් හොයාගන්නවා ලෝකයේ ම (විශ්වයේ ම?) එන්ට්‍රොපිය ආපසු හරවන තාක්ශණයක්. ඒකට චිත්‍රපටයේ කියන නම තමයි ඇල්ගොරිදම් (Algorithm). (සාමාන්‍ය භාවිතයේ දී ඇල්ගොරිදමයක් කියන්නේ තාර්කික දෙයක් වුනත් චිත්‍රපටයේදී ඇල්ගොරිදම් එක කියලා හඳුන්වන්නේ භෞතික දෙයක්.) මේක හොයාගත්තට පස්සේ ඇය තේරුම්ගන්නවා ඇය හොයාගත්තේ ලෝකය විනාශ කරන්න පුළුවන් තාක්ශණයක් කියලා. (මේක සමාන කරන්නේ ඕපන්හෛමර් න්‍යෂ්ටික බෝම්බය සොයාගැනීම ට.) ඉතින් ඇය ඒක කොටස් නවයකට වෙන් කරලා, අවකාශකාලයේ හංගනවා. (අපි සාමාන්‍යයෙන් දෙයක් හංගන්නේ අවකාශයේ විතරක් වුනාට, ඇයට පුළුවන් ඇය හොයාගත්තු තාක්ශණය ම පාවිච්චි කරලා කාලය ඇතුලෙත් යම් දෙයක් හංගන්න!) ඉන්පස්සේ ඇය මේ හංගපු තැන් වෙනත් අය අතට පත්වෙන එක වලක්වන්න සියදිවි නසාගන්නවා.</p><blockquote>එන්ට්‍රොපිය ආපසු හැරවීමෙන් ලෝකය විනාශ වෙන්නේ කොහොමද? එන්ට්‍රොපිය ආපසු හැරවීම නිසා කාලය ගත වෙන්නේ අනාගතයේ ඉඳලා අතීතය ට. ඒ කියන්නේ අතීතය සම්පූර්ණයෙන් ම මැකෙනවා. නැති වෙනවා. <br>අතීතය නැති වුනා ම අනාගතය පවතින්නේ කොහොමද? මේක විරුද්ධාභාෂයක්. කාලතරණය ගැන කියවෙන ඉතා ම ප්‍රසිද්ධ Grandfather Paradox එකේ කියැවෙන්නේ මේ ගැන. චිත්‍රපටයේ දී නීල්, මේ ගැන කතානායකයාට පැහැදිලි කරනවා. අපි අතීතයට ගිහින් අපේ තාත්තා ඉපදෙන්න කලින්, තාත්තාගේ තාත්තව, නැත්නම් අපේ සීයා ව මැරුවොත් මොකද වෙන්නේ? අපේ සීයා මැරුනා නම්, තාත්තා උපදින්නේ නෑ. එහෙනම් අපි උපදින්නේ නෑ. එහෙනම් සීයාව මරන්න කෙනෙක් නෑ. එහෙනම් සීයා මැරෙන්නේ නෑ. මේක විසඳුමක් නැති ගැටළුවක්. මේ වගේ ගැටළු තමයි විරුද්ධාභාෂ එහෙමත් නැත්නම් Paradox කියලා හඳුන්වන්නේ. ඉතින් මේකත් එහෙම විරුද්ධාභාෂයක්. ඒකට විසඳුමක්, උත්තරයක් දෙන්න බෑ.</blockquote><p>නමුත් අනාගතයේ ඉන්න මිනිස්සුන්ට ඕන වෙනවා මේ ඇල්ගොරිදම් එක හොයාගන්න. ඇයි? ඒ වෙනකොට අතීතයේ හිටි මිනිස්සු (අපි) විසින් කරන (කරපු?) දේවල් නිසා දේශගුණික විපර්යාස, පරිසර දූෂණය වගේ දේවල් වලින් ලෝකය විනාශ වෙලා ඉවරයි. ඉතිං ඒ ප්‍රතිඵල ආපසු හරවන්න නම්, එන්ට්‍රොපිය ආපහු හරවලා, කාලය ආපසු හරවන්න ඕන! ඒ සඳහා ඇල්ගොරිදම් එක හොයාගන්න ඕන. ඒ සඳහා අනාගතයේ ඉන්න “බලය ඇති” අය තෝරාගන්නේ කතාවේ දුශ්ඨයා, Sator ව. ඇයි? ඔහු හරි වෙලාවේ, හරි තැන (බිඳවැටුනු සෝවියට් රුසියාවේ, සැඟවණු න්‍යශ්ටික පර්යේශණ කරපු නගරයක, පැරණි න්‍යශ්ටික අවි සහ අපද්‍රව්‍ය සොයමින්) හිටපු නිසා. ඉතිං අනාගතයේ මිනිස්සු, පොළව යට වැලලූ පණිවිඩ හරහා Sator එක්ක පණිවිඩ හුවමාරු කරගන්නවා. ඒ එක්ක ම ඔහුට රත්රන් වලින් ගෙවීම් කරනවා.</p><blockquote>ඒ වුනත් ඇයි තමන්ගේ ම විනාශය වෙනුවෙන් Sator වැඩ කරන්නේ? <br>ඔහුට සුව කළ නොහැකි පිළිකාවක් තියෙනවා. (ඔහු න්‍යශ්ටික පර්යේශණ සිදුකරපු නගරයක හැදුනු කෙනෙක්. ඔහුට පිළිකාවක් වැළඳන්න තියෙන ඉඩ ඉතා ම වැඩියි!)<br>Sator හිතන විදිහ ගැන අපිට පෙන්නනවා තමන්ගේ බිරිඳ ගැන ඔහු හිතන විදිහෙන්. ඔහුගේ ම වචන වලින් “<strong>If I can’t have her, no one can”</strong>.<br>ඔහුට ජීවත් වෙන්න බැරි නම් ඔහුත් සමග ම ලෝකය විනාශ කරන එක තමයි Sator ගේ අරමුණ.</blockquote><p>ඉතින් අනාගතයේ මිනිස්සුන්ගේ උදව් ඇතුව Sator නිර්මාණය කරනවා එන්ට්‍රොපිය ආපසු හරවන්න පුළුවන් උපකරණයක්. (Turnstile කියලා චිත්‍රපටයේ හඳුන්වන්නේ මේ යන්ත්‍ර.) මේකෙන් ඇතුල් වෙන අයගේ (හා වස්තු වල) එන්ට්‍රොපියේ දිශාව (ආපස්සට හෝ ඉදිරියට) වෙනස් වෙනවා. ඉතින් Sator කරන්නේ මේ යන්ත්‍රයේ ආධාරයෙන් ඔහුගේ කණ්ඩායමේ කොටසක් කාලය හරහා ඉදිරියටත්, ඉතිරි කොටස කාලය හරහා ආපස්සටත් ගමන් කරන විදිහට කොටස් දෙකක් හදාගන්න එක. ඒකට <strong>Temporal pincer movement</strong> එකක් කියලා කියනවා. මේකේ වාසිය තමයි කාලය හරහා ආපස්සට එන අය අනාගතයේ සිදුවූ දේ දන්න නිසා, ඒ ගැන කාලය දිගේ ඉදිරියට එන අයට ඒ තොරතුරු දෙන්න පුළුවන් වීම. ඒ නිසා Sator ට පුළුවන් “ගොඩක් වෙලාවට” අනිත් අයට වඩා ඉස්සරහින් ඉන්න.</p><p>කතානායකයා දැනගන්නවා Sator, Oslo වල තියෙන Freeport (ධනවත් අයට, ලෝකයේ වටිනා ම කලා නිර්මාණ ඇතුළු වටිනා දේවල් බදු වලින් නිදහස් ව තියලා තියාගන්න පුළුවන් වෙන්න හදලා තියෙන අධි ආරක්ෂිත ගබඩා) එකක මොකක් හරි වැදගත් දෙයක් හංගලා තියෙනවා කියලා. ඔහු නීල්ගෙත්, මහීර්ගෙත් සහය ඇතුව, ගුවන්යානයක් හප්පලා, එතන ගිනි නිවීම් ක්‍රියාවලියේ තියෙන දුර්වලකම් පාවිච්චි කරලා, Oslo වල තියෙන Freeport එක ඇතුලට යනවා. එතනදී කතානායකයාටත්, නීල්ටත්, හම්බුවෙනවා Turnstile එකකින් එලියට එන දෙන්නෙක්. කෙනෙක් කාලය හරහා ඉදිරියටත්, අනිත් කෙනා ආපස්සටත්. මෙතනදී කතානායකයා ඒ කෙනෙක් එක්ක සටන් කළත්, ඔහු පැනගන්නවා.</p><p>පස්සේ Kat ගේ උදව් ඇතුව කතානායකයා Sator එක්ක සම්බන්ධතාවයක් හදාගන්නේ, Sator කරන්න සූදානම් වෙන්නේ මොකද්ද කියලා දැනගන්න. ඒ අනුව කතානායකයා දැනගන්නවා Sator ට Plutonium 241 අවශ්‍ය බව. කතානායකයා Sator ට Plutonium 241 දෙන්න පොරොන්දු වෙනවා, Kat ව නිදහස් කිරීමේ පොරොන්දුව මත. නමුත් කතානායකයා Sator ට පොරොන්දු වුන විදිහට Plutonium නොදෙන බව තමන්ගේ Temporal Pincer Movement එක හරහා දැනගන්න Sator, Kat ට එන්ට්‍රොපිය ප්‍රතිවර්ත කරපු උණ්ඩයකින් (inverted bullet එකකින්) වෙඩි තියනවා.</p><blockquote>සාමාන්‍ය උණ්ඩයකට වඩා මේ ප්‍රතිවර්ත කළ (inverted) උණ්ඩ වලින් වෙන හානිය වැඩියි. ඒකට හේතුව එන්ට්‍රොපිය වැඩිවෙන (ප්‍රතිවර්ත නොකරපු) අවස්ථාවේ කෙනෙක් ට මේ උණ්ඩයක් වැදුනම උණ්ඩයේ තුවාලයට අමතරව විකිරණශීලීතාවයෙන් (Radiation) හානි සිදුවීම.</blockquote><p>Kat ව බේරගන්න තියෙන එක ම විදිහ තමයි Kat ව turnstile එකක් හරහා යවලා, Kat ගේ එන්ට්‍රොපි එක ආපස්සට හරවන එක. එතකොට අර විකිරණශීලී හානි නැති වෙන නිසා Kat ව සුව කරගන්න පුළුවන්. නමුත් එතනදී කතානායකයා වගේ ම අපිත් දැනගන්නවා එන්ට්‍රොපිය ආපසු හැරවීම සරළ දෙයක් නොවන බව. එහෙම ප්‍රතිවර්ත කරපු (inverted) කෙනෙක් ට සාමාන්‍ය වාතය ආඝ්‍රාහණය කරන්න බෑ. පෙනහළු වලින් ඒ වාතය පෙරාගන්න බෑ, ඒ නිසා වෙන ම වායු සැපයුමක් අවශ්‍යය වෙනවා. තමන් ප්‍රතිවර්ත වුනත් බාහිර ලෝකය ප්‍රතිවර්ත නැති නිසා ලැබෙන භෞතින අත්දැකීම් වෙනස්. සාමාන්‍යයෙන් ශක්තිය ගලන දිශාවට ප්‍රතිවිරුද්ධව ශක්තිය ගලන නිසා, ප්‍රතිවර්ත වූ කෙනෙක් ගින්නක ට මුහුණු දුන්නොත්, ඔහු අධි ශීතල (Hypothermia) තත්ත්වයට පත්වෙනවා. (කතානායකයා මූණදෙන අනතුරේදී සිදුවෙන්නේ මේක.)</p><blockquote>සාමාන්‍යයෙන් වෙන්නේ උෂ්ණත්වය වැඩි තැන ඉඳලා උෂ්ණත්වය අඩු තැනට තාපය (ශක්තිය) ගලන එක. ප්‍රතිවර්ත කෙනෙක් (හෝ වස්තුවක) ගේ වෙන්නේ උෂ්ණත්වය අඩු තැන ඉඳලා වැඩි තැනට තාපය (ශක්තිය) ගලන එක. ඒ නිසා වැඩි උෂ්ණත්වයේ තියෙන වස්තුව තව දුරටත් රත් වෙනකොට, අඩු උෂ්ණත්වයේ තියෙන වස්තුව තව දුරටත් සීතල වෙනවා!</blockquote><blockquote>(මෙතනදී ගින්න අතරේදී වාහනයේ වීදුරු අයිස් වීම නම් මට අනුව නෝලන් කරපු අත්වැරැද්දක්. කතානායකයා ප්‍රතිවර්ත වුනත් වාහනය ප්‍රතිවර්ත නොවුන නිසා, වාහනයේ වීදුරුවේ අයිස් බැඳෙන්න හේතුවක් නෑ)</blockquote><p>මේ වගේ ව්‍යාකූලතා තිබුනත්, කතානායකයා, Neil සහ Kat තමන්ව ප්‍රතිවර්ත කරගන්නවා. මෙතනදී මතුවෙන ප්‍රශ්නය තමයි, ඔවුන් නැවත තමන් ව එන්ට්‍රොපිය වැඩි වෙන පැත්තට ප්‍රතිවර්ත කරගන්නේ කොහොමද කියන එක. එතනදී කතානායකයාත්, නීලුත් මතක් කරගන්නේ කලින් තමන්ට Oslo වල දී හමු වූ Turnstile එක! දැන් ප්‍රතිවර්තවෙලා කාලය හරහා ආපස්සට යන නීල් සහ කතානායකයා, Olso වල තමන් කලින් ගුවන් යානයක් හප්පලා ඇතුල් වුන දවසේ ම නැවතත් Turnstile එක ඇතුලට යනවා.</p><p>අපි මුලින් දකින කතානායකයා එක්ක සටන් කරන අනිත් පුද්ගලයා කතානායකයා ම බව මෙතනදී තේරුම් යනවා. ඒ අනුව, ඒ “වෙලාවේ” දී කතානායකයාගේ ම පිටපත් තුනක්, එක ම වෙලාවේ පවතිනවා.</p><ul><li>සාමාන්‍ය විදිහට (මුල ඉඳලා) කාලය හරහා එන කතානායකයා</li><li>අනාගතයේ ඉඳලා කාලය හරහා ආපස්සට එන කතානායකයා</li><li>කාලය හරහා ආපස්සට ඇවිත්, turnstile එකෙන් ආපහු එන්ට්‍රොපිය ඉදිරියට හරවාගෙන පිටත් වෙන (නීල් සමග සටන් කරලා පැනලා යන) කතානායකයා.</li></ul><blockquote>මෙතනදී මතක තියාගන්න ඕන කාරණය තමයි මේ විදිහට එන්ට්‍රොපිය ආපසු හැරවීම හරහා වෙන්නේ අපි සාමාන්‍යයෙන් විද්‍යා ප්‍රබන්ධ වල දකින කාල තරණය වගේ අතීතයේ හෝ අනාගතයේ නිශ්චිත මොහොතකට ප්‍රාදුර්භූත වීමක් නොවන බව. මෙතනදී සිද්ධ වෙන්නේ කාලය ගතවන දිශාව වෙනස් වීම විතරයි. ඒ නිසා තමයි turnstile එකේ වීදුරුව හරහා බලද්දී තමන් අනිත් පැත්තෙන් එලියට එනවා පේන්නේ. Turnstile එකෙන් ඇතුලට යන මොහොතත්, අනිත් පැත්තෙන් එලියට එන මොහොතත් එකම යි. වෙනස් වෙන්නේ එතැන ඉඳලා කාලය ගත වෙන දිශාව!</blockquote><p>මෙහෙම ගිහින් කතානායකයා දැනගන්නවා Sator ඇල්ගොරිදම් එක න්‍යෂ්ටික පිපිරීමක කේන්ද්‍රයේ (Epicenter එකේ) තැන්පත් කරලා, එතැන පිපිරීම සිදුකරන්න නියමිත බව. ඒකට හේතුව න්‍යෂ්ටික පිපුරුමක් වුන තැන තව සෑහෙන කාලයකට මිනිසුන්ට ළඟා වෙන්න නොහැකි නිසා, වර්තමානයේ මිනිස්සුන්ට ඒක ලබාගන්න නොහැකි වීමත්, ඒ නිසා අනාගතයේ මිනිස්සුන්ට ඇල්ගොරිදම් එක ලබාගන්න පුළුවන් වීමත්. මේ පිපුරුම Sator ගේ අතේ තියෙන heart beat monitor එකට සම්බන්ධ කරලා තියෙන්නේ, Sator ගේ හෘද ස්පන්ධනය නැවතුන ගමන්, බෝම්බය පුපුරන විදිහට.</p><p>තමන්ගේ මරණ දිනය විදිහට Sator තෝරගන්නේ Kat එක්ක වියට්නාමයේ නිවාඩුව ගත කරපු දිනය. ඒ දවසේ ම තමයි චිත්‍රපටයේ ආරම්භයේ අපි දකින ඔපෙරාවේ සිද්ධිය සිදුවෙන්නෙත්. ඉතිං මේ පිපිරීමට කලින් ඇල්ගොරිදම් එක එතැනින් අයින් කරන එක තමයි කතානායකයාගේ සැලැසුම. අපි දකින විදිහට මේ සැලසුම මෙහෙයවන්නේ ප්‍රියා කියන ඉන්දියානු ආයුධ වෙළඳාම් කරන කාන්තාව. කතානායකයා වැඩ කරන්නේ ඇය යටතේ. එතනදී මෙහෙයුම සාර්ථක වුනා ම Kat ගේ ජීවිතයට හානියක් නොකරන්න කියලා කතානායකයා ප්‍රියා ව පොරොන්දු කරගන්නවා.</p><p>සැලැසුමේ විදිහට කලින් කාලය හරහා ආපස්සට ආපු Kat, නැවත කාලය දිගේ ඉදිරියට ගමන් කරන්න ප්‍රතිවර්ත වෙලා, වියට්නාමයට යන්නේ, Sator ගේ සියදිවි නසාගැනීම පරක්කු කරන්න. ඒ අතරේ දී කතානායකයා, Neil, Ives, Wheeler ඇතුළු කණ්ඩායම් දෙකක් පිපුරුම සිද්ධ වෙන තැනට යනවා ඇල්ගොරිදම් එක තමන් අතට ගන්න. මේ කණ්ඩායම් දෙකෙන් එක (රතු) කණ්ඩායමක් කාලය දිගේ ඉදිරියටත්, අනෙක් (නිල්) කණ්ඩායම කාලය දිගේ ආපස්සටත් ගමන් කරන්න නියමිතයි. කණ්ඩායම් දෙකට ම විනාඩි දහයක කාලයක් තියෙනවා මෙහෙයුම සම්පූර්ණ කරන්න. මෙතනදී කතානායකයා රතු කණ්ඩායමටත්, නීල් නිල් කණ්ඩායමටත් එකතු වෙනවා.</p><p>මේ මෙහෙයුම අතරෙදි නීල් දකිනවා හෙලිකොප්ටරයකින් එන සතුරු සොල්දාදුවෙක් පිපිරුම් කේන්ද්‍රයට ඇතුල් වෙන උමග ළඟ බෝම්බයක් අටවලා උමගට ඇතුල් වෙනවා. (මේක නීල් ට පේන්නේ අග සිට මුලට, නීල් දැන් ඉන්නේ ප්‍රතිවර්ත වෙලා නිසා.) මේ ගැන කතානායකයාට අනතුරු අඟවන්න නීල් පිපිරුම් ස්ථානයේ තියෙන turnstile එකක් ආධාරයෙන් නැවත ප්‍රතිවර්ත වෙනවා. නමුත් නීල් ප්‍රතිවර්ත වෙලා වාහනයකින් කතානායකයා සහ Ives පස්සෙන් ආවත් ඔවුන්ව වලක්වන්න නීල් ට බැරි වෙනවා. උමග පුපුරලා කතානායකයා සහ Ives ඇතුලේ හිරවෙනවා. ඊට පස්සේ නීල් කරන්නේ හමුදා වාහනය අරගෙන පිපුරුමේ ඉහල විවරය ළඟට ඇවිත්, කතානායකයාටත්, Ivesටත් එලියට එන්න ආධාරකයක් දෙන්න යන එක.</p><p>මේ අතරේ කතානායකයා සහ Ives උමග ඇතුලේ දොරක් ළඟ හිරවෙනවා. එතන මැරුණ නිල් කණ්ඩායමේ සාමාජිකයෙක්ගේ මළසිරුර දකින කතානායකයාට මතක් වෙනවා තමන් ව කලින් ඔපෙරාවේදී බේරාගත් කෙනා විදිහ ම රතු නූලක් මේ මැරිච්ච සාමාජිකයාගේ කරමල්ලේ ද තියෙන බව, ඒ කියන්නේ, තමන්ව කලින් ඔපෙරාවේදී බේරාගත් කෙනා මෙතැන මැරිලා තියෙන බව. <br>ඒ දොර ළඟ දී Sator ගේ හමුදාවේ සාමාජිකයා කතානායකයාට වෙඩි තියන තැන දී, අර මැරුණු නිල් කණ්ඩායමේ සාමාජිකයා නැගිටලා ඒ උණ්ඩයට මුහුණ දෙනවා. ඒ කියන්නේ, ඒ මැරිලා ඉන්නේ ප්‍රතිවර්ත වූ කෙනෙක්. ඔහු කාලය හරහා ආපස්සට එන අතරේ, හිරවුන දොර ඇරලා, කතානායකයාට තියපු වෙඩි උණ්ඩයට මුහුණ දෙනවා. මේක අපිට පේන්නේ ආපස්සට, මැරුණ තැන ඉඳලා මුලට.</p><p>ඊට පස්සේ ඇල්ගොරිදම් එක තමන් අතට ගන්න කතානායකයා, Ives එක්ක Neil උඩින් දෙන ආධාරකයේ එල්ලිලා එලියට එනවා, මේ වෙලාවේදී ම Kat, Sator ට වෙඩි තියනවා. අවසානයේ පිපිරුමට කලින් කොහොමහරි ඇල්ගොරිදම් එක තමන් අතට ගන්න කතානායකයා ඇතුළු පිරිසට පුළුවන් වෙනවා!</p><p>අන්තිමට අපි දකිනවා ඇල්ගොරිදම් එක කොටස් තුනකට වෙන් කරලා කතානායකයා, Neil සහ Ives අතරේ බෙදාගන්නවා. ඇල්ගොරිදම් එක ගැන එතනින් එහාට කිසිම කෙනෙක්ට දැනගන්න ඉඩ නොතියන එක තමන් බාරගන්න අවශ්‍ය බව ඔවුන් එකඟ වෙනවා. එතැනින් නීල් හැරිලා යනකොට, කතානායකයා දකිනවා අර රතු පාට නූල නීල්ගේ කර මල්ලේ තියෙන බව. ඒ කියන්නේ නීල් මේ යන්නේ ආයෙම ප්‍රතිවර්ත වෙලා, උමග ඇතුලට. නීල් තමයි කතානායකයාට එන උණ්ඩයට මුහුණ දීලා මැරෙන්නේ!</p><p>මෙතැනදී කතානායකයා අහනවා නීල් ව TENET එකට බඳව ගත්තේ කවුද කියලා. නීල් කියන්නේ, තමන්ව බඳවගත්තේ කතානායකයා කියලා! නීල් ට අනුව මේ කතානායකයා නීල්ව අඳුනගන්න මොහාත වගේ ම, නීල් කතානායකයට සමුදෙන මොහොත.<br>දැන් පැහැදිලි වෙනවා නීල් කතානායකයාව මුලින් ම හම්බවෙන වෙලාවේ කතා නායකයා ගැන විස්තර දැනගෙන හිටියේ කොහොමද කියලා.</p><blockquote>සමහර තැන් වල නීල් කියන්නේ Kat ගේ පුතා වෙන්න පුළුවන් කියලා අදහසක් තියෙනවා. ඒක වෙන්න පුළුවන් වගේ ම සෑහෙන ලස්සන වැඩක්. Kat ගේ පුතාගෙත් Neilගෙත් පෙනුමේ සමාන ලක්ශණ තියෙනවා.</blockquote><p>මෙතනදී කතානායකයා තේරුම් ගන්නවා මේ සම්පූර්ණ සැලැස්ම ම, තමන්ගේ එකක් බව. ඒ කියන්නේ TENET කියන්නේ කතානායකයා විසින්, මේ විනාශය නවත්තන්න අනාගතයේදී බිහි කරන සංවිධානය බව! ප්‍රියා ව මෙහෙයවන්නේත් අනාගතයේ සිටින කතානායකයා ම බව!</p><p>ඒ අනුව මේ සම්පූර්ණ කතාව ම තනි Temporal Pincer Movement එකක්!</p><p>මේ අවසානය පැහැදිලි කරගන්න නම්, මේ කතාවේ විස්තර වෙන කාලතරණ සංකල්පය තව ටිකක් විස්තර කරගන්න ඕන.</p><p>මේ කතාවේ එන කාල තරණය සංවෘත පුඩු කාල තරණයක් (Closed-loop time travel එකක්). සරළව, නීල් ගේ වචන වලින් ම කියනවා නම්, What’s happened, happened. යමක් දැනට ම සිදු වෙලා නම්, ඒක දැනටම සිදුවෙලා ඉවරයි. මේ ආකාරයේ කාලතරණ වල විශේෂත්වය තමයි, නිශ්චිත අගක් හෝ මුලක් නැති වීම. සිද්දීන් සියල්ල දාමයක් විදිහට එකිනෙකට බැඳිලා තිබීම.</p><p>උදාහරණයක් විදිහට කතා නායකයා බේරෙන්න නම්, උමග ඇතුලෙදි නීල් මැරෙන්න ඕන. නීල් එහෙම මැරෙන්න නම්, කතා නායකයා අනාගතයේදී නීල් ව TENET එකට බඳවගන්න ඕන. නීල්ව බඳවගන්න නම්, කතා නායකයා බේරෙන්න ඕන. කතා නායකයා බේරෙන්න නම්, නීල් මැරෙන්න ඕන…</p><p>තව සංකීර්ණ උදාහරණයක් ගත්තොත්, TENET කියන්නේ කතානායකයා අනාගතයේදී හදන සංවිධානය. ඒක හදන්න නම්, කතානායකයා දැන් TENET එකට බැඳෙන්න ඕන. මේ සිද්ධි දෙකෙන් මුලින් සිදු වෙන්නේ කෝකද කියලා හිතන්න බෑ. මේ වගේ විරුද්ධාභාෂ වලට Predestination Paradox කියලා කියනවා.</p><p>එතනින් අපිට චිත්‍රපටයේ එන ප්‍රධාන දෙබසකට යන්න පුළුවන්. කතානායකයාට මුලින් හම්බවෙන විද්‍යාඥවරිය කතානායකයාට කියනවා එන්ට්‍රොපිය ආපසු හැරවූ වස්තුවක් අතට ගන්න නම්, අපි මුලින් ම ඒක අත්ඇරලා තියෙන්න ඕන කියලා. ඒ කියන්නේ, වස්තුව වැටිලා තියෙනවා, ඊට පස්සේ අපි ඒක අතඅරිනවා. ඊට පස්සේ තමයි ඒ වස්තුව අතට එන්නේ. කතා නායකයා අහනවා, ඵලයට කලින් හේතුව පවතින්න ඕන නේද (But cause comes befoe effect) කියලා. ඒකට පස්සේ ඔහු අහනවා What about the free will? (ස්වච්ඡන්දතාවයට මොකද වෙන්නේ?) කියලා. ඒකට ඇය දෙන උත්තරය තමයි, අපි අත එතැන තිබ්බේ නැතිනම්, උණ්ඩය අතට නොඑන බව. ඒ කියන්නේ අත එතන තියනවද, නැද්ද කියන ස්වච්ඡන්දය තමන් අතේ තියෙන බව).</p><blockquote>මේ විද්‍යාඥවරිය සමහරවිට අනාගතයේදී ඇල්ගොරිදම් එක හදන විද්‍යාඥවරිය වෙන්න පුළුවන්. කතා නායකයා, “You didn’t make it?” කියලා අහද්දී ඇය කියන්නේ “No, we don’t know how yet” කියලා. ඒ කියන්නේ මේක හදන හැටි “තාම” දන්නේ නැති බව.</blockquote><p>නමුත් කතාව අවසාවයේදී අපිට තේරෙන දේ තමයි, අත තියනවාද නැද්ද කියන තීරණය තමන් අතේ නැති බව. නීල් ගේ වචන වලින් “What’s happened’s happened” (යමක් සිදු වෙලා නම්, ඒක දැනටම සිදුවෙලා ඉවරයි). මේ අනුව නෝලන් අහන්නේ ඉතා පරණ දාර්ශනික ප්‍රශ්නයක්; අපිට ස්වච්ඡන්දතාව තියෙනවා ද නැද්ද?</p><p>සරළ ව ඇහුවොත්, අපි ගන්න තීරණ ඇත්තට ම අපි ගන්නා තීරණ ද? සිදුවීමට නියමිත සියලු ම දේ කලින් ම තීරණය වෙලා අවසන් ද? අපි නිකන් ම නිකං ඒ තීරණය වූ කතාවේ නළුවන් විතර ද? අපි ජීවත්වන්නේ නිශ්චිත විශ්වයක (deterministic universe එකක) ද? නෝලන් අපෙන් අහන්නේ ඒක!</p><p>Visit Blog: <a href="https://thisaru.me/thoughts/tenet/">Tenet කියවමු</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3c1d543d8125" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Authenticate A Shopify App Using OAuth — The Ballerina Way]]></title>
            <link>https://medium.com/ballerina-techblog/authenticate-a-shopify-app-using-oauth-the-ballerina-way-f827ab99f576?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/f827ab99f576</guid>
            <category><![CDATA[shopify-apps]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[authentication]]></category>
            <category><![CDATA[shopify-development]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 02 Jun 2020 21:55:14 GMT</pubDate>
            <atom:updated>2025-06-28T16:30:11.352Z</atom:updated>
            <content:encoded><![CDATA[<h3>Authenticate A Shopify App Using OAuth — The Ballerina Way</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZcLoTz-SIp6Z3ywkc3nCfA.jpeg" /></figure><blockquote>Note: The code in the article is now updated to Ballerina SwanLake (2201)</blockquote><p>During this pandemic, we now feel the importance of E-commerce more than ever. <a href="https://www.shopify.com/">Shopify</a> is an E commerce platform which provides merchants to create an online store easily.</p><p>We, as developers can create various apps on Shopify to help merchants to handle their stores. In order to install a Shopify app, merchants needs to authenticate the app, and the app needs an access token to access to the stores.</p><p>I was trying to create a Shopify app (for a completely different reason). Although there are many documentations, I spent many hours to find a way to authenticate my app. (Sounds dumb, yeah!).</p><p>Finally, I succeeded, and wanted to share the way I accomplished this using <a href="https://ballerina.io/">Ballerina</a>. Ballerina is specifically designed for network applications. It is pretty much simple to do this, even compared to the <a href="https://www.shopify.com/partners/blog/shopify-admin-authenticate-app">solution provided by the Shopify themselves</a>! You only need Ballerina for this.</p><blockquote>If you haven’t <a href="https://ballerina.io/downloads/">downloaded Ballerina</a> yet, do it now.</blockquote><p>First, let me briefly explain the authentication process. This is explained in detail at <a href="https://shopify.dev/tutorials/authenticate-with-oauth">shopify documentation</a>. There are 5 steps (These steps are defined by me, don’t take it as an official statement).</p><ol><li>Merchant sends a request to install the app. (This sends a request to the App installation endpoint).</li><li>App installation endpoint will then redirects the request to the shopify admin API, with the required scopes, and a redirect_link. (This redirect_link is the link to the endpoint described in the step 4 below).</li><li>Then the Shopify will show a prompt to the user to review the scopes and authorize the installation request.</li><li>Then the Shopify admin API sends a request to the app. (This request is sent to the redirect_link described in the step 2).</li><li>The app endpoint then validate the request from the Shopify (Will describe this later), and sends a request back to Shopify admin API to get an access token.</li></ol><p>First thing is to create an App and get the API key and the API secret key for the App. Creating an app is really easy, and you can follow the instructions provided by <a href="https://shopify.dev/concepts/apps#types-of-apps">Shopify documentation</a> for this. I’m not going to explain this further since that isn’t my intention here.</p><p>But there’s one important thing. You have to provide the aforementioned endpoint URLs in the Shopify app settings. Use the following settings in your URL section in the app settings.</p><blockquote>For this example, I used localhost. You may replace these URLs with your host, but for testing, using localhost is much easier.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/987/1*1j3AdFpxfbnsE_ei5Ybdzg.png" /></figure><p>Following are the URLs</p><ul><li>App URL<br>When a merchant tries to install your app, this is the place where it redirects the merchant. In this example, we are using install endpoint for this.</li><li>Whitelisted Redirection URL(s)<br>These are the redirect URLs used for authentication purposes. For this example, we only use the get_token endpoint for this. Make sure to use the exact endpoint url here, providing just the domain will not work.</li></ul><p>First get your API key and API secret key from the Shopify app page. We need this to authenticate the app. It looks like following:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/473/1*o1r6xiGtNfwh23KtFs4ZNA.png" /></figure><p>Now we are going to write the install endpoint using Ballerina. This endpoint have to do the following:</p><ul><li>Read the query parameters from the request and retrieve the store name.</li><li>Send a request to Shopify admin API, with client_id, scope, and the redirect_uri as query parameters.</li></ul><p>Following is the ballerina service for this. This is just for the explanation. The complete code can be found at the end of this article.</p><pre>service on new http:Listener(8080) {<br>  resource function get <strong>install</strong>(string[] shops) returns error? {<br>  string redirectUrl = check url:encode(getTokenResource, &quot;UTF-8&quot;);<br>  string shop = shops[0];</pre><pre>  string queryParameters = string `?client_id=${API_KEY}&amp;scope=${scopes}&amp;redirect_uri=${redirectUrl&amp;state=${NONCE}&amp;grant_options[]=${accessType}`;<br>  string shopUrl = string `https://${shop}${authorizeApiPath}${queryParameters}`;<br>  http:Response response = new;</pre><pre>  var result = caller-&gt;redirect(&lt;@untainted&gt;response, 301, [&lt;@untainted&gt;shopUrl]);<br>}</pre><p>First we need to retrieve the store name from the query parameters. <a href="https://ballerina.io/learn/api-docs/ballerina/http/index.html">Ballerina HTTP module</a> provides APIs for retrieve query parameters from the request path easily.</p><p>Then using the shop name, we build the shop URL to redirect the request to authenticate the app. AS mentioned earlier, we need to add the following query parameters to the request path.</p><ul><li>API key (client_id)<br>The API key of the app, which we received from the shopify.</li><li>Scopes (scope)<br>These are the access scopes, which are required for our app. There are <a href="https://shopify.dev/docs/admin-api/access-scopes">a lot of app scopes</a> available, and you can decide what scopes needed for the app depending on the requirement. These should be provided as a comma separated string.</li><li>Redirect URI (redirecrt_uri)<br>This is the app endpoint link, which is used to request the access token from the shopify, as described previously. It should be encoded before sending. Ballerina provides an easy way to encode a URL using <a href="https://ballerina.io/learn/api-docs/ballerina/encoding/index.html">Ballerina encoding module</a>.</li><li>State<br>This is a random nonce string. It is used to validate the request when it comes back from the Shopify admin API. For the example, we just use a predefined string.</li><li>Grant Options<br>This is the type of access token we are requesting. There are two types. The offline access is used here, which provides kinda permanent access token. <a href="https://shopify.dev/concepts/about-apis/authentication#api-access-modes">Read more about API access modes here</a>.</li></ul><p>Then we create a new, empty http:Response object to send to shopify admin API. This response is needed to redirect the request to the Shopify admin API. It has nothing to do with anything with the authentication process.</p><p>Then the request is redirected to the previously built shop URL. Note the status code 301 (http:REDIRECT_MOVED_PREMANENTLY_301) is used when redirecting. This must be 301, otherwise the redirect will fail.</p><blockquote>The @untainted annotation is used to untaint the tainted values in Ballerina. Read more about <a href="https://ballerina.io/learn/by-example/taint-checking.html">Ballerina taint checking</a>.</blockquote><p>Then shopify will redirect this back with a code. We use this code to retrieve an access token. To get this access token we have to implement the get_token endpoint. Following is the code. (This resource function also resides inside the service we created before).</p><pre>resource function <strong>get_token</strong>(http:Caller caller, http:Request request) {<br>  map&lt;string[]&gt; requestParameters = request.getQueryParams();<br>  string path = removeHmacParameter(requestParameters);</pre><pre>  string[] shops = &lt;string[]&gt;requestParameters[&quot;shop&quot;];<br>  string shop = shops[0];<br>  string[] hmacs = &lt;string[]&gt;requestParameters[&quot;hmac&quot;];<br>  string hmac = hmacs[0];<br>  string[] states = &lt;string[]&gt;requestParameters[&quot;state&quot;];=<br>  string state = states[0];<br>  string[] codes = &lt;string[]&gt;requestParameters[&quot;code&quot;];<br>  string code = codes[0];</pre><pre>  string redirectUrl;<br>  http:Response response = new;<br>  boolean isValid = validateRequest(path, hmac, state);</pre><pre>  if (isValid) {<br>    log:printInfo(&quot;Valid request&quot;);</pre><pre>    json requestBody = {<br>      client_id: API_KEY,<br>      client_secret: API_SECRET,<br>      code: code<br>    };<br>    request.setJsonPayload(&lt;@untainted&gt;requestBody);<br>    string accessTokenUrl = &quot;https://&quot; + shop + accessTokenApiPath;<br>    http:Client httpClient = new (accessTokenUrl);<br>    var result = httpClient-&gt;post(&quot;/&quot;, &lt;@untainted&gt;request);<br>    if (result is http:Response) {<br>      json responsePayload = &lt;json&gt; result.getJsonPayload();<br>      string accessToken = responsePayload.access_token.toString();<br>      log:printInfo(&quot;Access Token: &quot; + accessToken);<br>    }<br>    redirectUrl = &quot;https://your.app.com/success&quot;;<br>  } else {<br>    log:printError(&quot;Request is invalid&quot;);<br>    redirectUrl = &quot;https://your.app.com/failure&quot;;<br>  }<br>  var redirectResult = caller-&gt;redirect(response, http:REDIRECT_MOVED_PERMANENTLY_301, [redirectUrl]);<br>}</pre><p>The request contains the following query paramters:</p><ul><li>code<br>Used to retrieve the access token from the Shopify.</li><li>shop<br>The name of the shop.</li><li>hmac<br>Used to verify the authenticity of the request.</li><li>state<br>The nonce value sent from the previous step.</li><li>timestamp<br>This is used to calculate the HMAC value.</li></ul><p>Now the request should be validated using the HMAC value. To do this, we need to remove the hmac parameter from the query parameters, and then calculate the HMAC value. Then comparing the generated HMAC value and the received HMAC value, the authenticity of the request can be validated. The <a href="https://ballerina.io/learn/api-docs/ballerina/crypto/index.html">Ballerina Crypto module</a> can be used for this. Following functions does this:</p><pre>function <strong>validateRequest</strong>(string path, string hmac, string state) returns boolean {<br>  if (NONCE != state) {<br>    return false;<br>  }<br>  byte[] pathValue = path.toBytes();<br>  byte[] hashKey = API_SECRET.toBytes();<br>  byte[] resultHmacBytes = crypto:hmacSha256(pathValue, hashKey);<br>  string resultHmac =  resultHmacBytes.toBase16();<br>  return resultHmac == hmac;<br>}</pre><pre>function <strong>removeHmacParameter</strong>(map&lt;string[]&gt; requestParameters) returns string {<br>  string result = &quot;&quot;;<br>  string[] keys = requestParameters.keys();<br>  foreach string key in keys {<br>    if (key != &quot;hmac&quot;) {<br>      string[] value = &lt;string[]&gt; requestParameters[key];<br>      result = result + &quot;&amp;&quot; + key + &quot;=&quot; + value[0];<br>    }<br>  }<br>  <em>// Remove the first `&amp;` character<br>  </em>return &#39;string:substring(result, 1);<br>}</pre><p>The removeHmacParameter function will remove the hmac parameter from the query parameters and returns a string. Then the validateRequest function will compare the nonce value and the hmac value, and return a boolean value to indicate whether the request is a valid request from the Shopify or a malicious one.</p><p>Once the request is validated, we can proceed to retrieve the access token from the Shopify admin API.</p><p>Then we create a Ballerina http:Request object to send to the Shopify admin API to retrieve the access token. This request contains a JSON body. We create this JSON object using Ballerina. Since json is a built-in type in Ballerina, this is quite simple. The JSON should have the API key, the API secret key (which are obtained in our app page), and the code sent by Shopify. After creating the JSON object, it is set as the request body, and then a post call is sent to the authenticate endpoint of the Shopify admin API.</p><p>The Shopify API will then send a response with the access token. This token is sent inside the response body, as a JSON. The response payload is read and the access token is retrieved as shown in the code.</p><p>We only print the access token here, but you can save this access token to communicate with the store in future.</p><p>Finally, we redirect the request from the Shopify admin API back to the shop URL. This URL can be anything. You can use your app home page or anywhere else, so that after installing the app, merchant is redirected to that URL.</p><p>That’s it! We now have an access token to communicate with a shopify store, who installed our Shopify app.</p><p>Here’s the complete code for the example:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b04aa000e5d636bf11bfdefc76097bfb/href">https://medium.com/media/b04aa000e5d636bf11bfdefc76097bfb/href</a></iframe><p>This is it. This is all you want to authorize a Shopify app. Hope this helps you out. If you have any questions, catch me on Twitter.</p><p><a href="https://twitter.com/ThisaruGuruge">JavaScript is not available.</a></p><blockquote>Note: Ballerina and Shopify are registered trademarks of the respective companies.</blockquote><p>Visit my blog: <a href="https://thisaru.me/thoughts/graphql-federation-with-ballerina-part-i/">https://thisaru.me/thoughts</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f827ab99f576" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/authenticate-a-shopify-app-using-oauth-the-ballerina-way-f827ab99f576">Authenticate A Shopify App Using OAuth — The Ballerina Way</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Creating A Local Kafka Cluster for Testing: A Weekend Project]]></title>
            <link>https://medium.com/swlh/creating-a-local-kafka-cluster-for-testing-a-weekend-project-5d47e97fa9b1?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/5d47e97fa9b1</guid>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[apache-kafka]]></category>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[kafka]]></category>
            <category><![CDATA[kafka-cluster]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Sun, 10 May 2020 19:02:43 GMT</pubDate>
            <atom:updated>2025-06-28T16:30:31.505Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>TL; DR;<br>I have implemented a local Kafka cluster to use in tests. <a href="https://github.com/ThisaruGuruge/local-kafka-cluster">Source code is here</a>.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/820/1*Zaun06N_MAA36GQiinRR8Q.png" /></figure><p>I’ve been working in developing <a href="https://ballerina.io/learn/api-docs/ballerina/kafka/index.html">Ballerina Kafka module</a> for some time now. It’s been PITA to test this connector! I needed a Kafka cluster to start, then shut down, then start gain, etc.</p><p>Some of the requirements I had are:</p><ul><li>To start a Kafka server programatically, with some custom settings, like custom port, custom security protocol, etc.</li><li>To consumer messages (which I produced using my ballerina producers) programatically and check them.</li><li>To produce messages to a specific topic programmatically. (So that I can consume them using my ballerina consumers).</li><li>To create topics in the cluster programmatically.</li></ul><p>I searched for a solution, and the most of the solutions involved using a docker image, which wasn’t helpful in my case. I did not have a way to test these in a docker environment.</p><p>Then I used <a href="https://debezium.io/">Debezium</a>, which is not intended to use in these kind of situations, but became helpful. Although it worked, there were some complexities in working with Debezium in the tests.</p><p>Then I got to know about the <a href="https://github.com/apache/flume">Apache Flume</a>, where they create a local Kafka cluster for their tests. It is almost what I searched for, but still missing some functionalities.</p><p>Then I thought of implementing my own Kafka cluster, by combining the both. I did this using the builder design pattern, to so that I can create the cluster step-by-step to reduce the complexity. The cluster has the following components:</p><ul><li>A ZooKeeper server</li><li>One or more Kafka Servers</li><li>An optional Kafka consumer</li><li>An optional Kafka Producer</li></ul><blockquote>Note: This setup is only used for testing purposes. It is not recommended to use in a production environment at all!</blockquote><p>First I implemented the LocalKafkaServer which is the Kafka server used in the Kafka cluster. I used KafkaServer in Apache Kafka library for this. Following is the code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/0a05be9aa8a55efbe2b177970b067a0d/href">https://medium.com/media/0a05be9aa8a55efbe2b177970b067a0d/href</a></iframe><p>Then I created the ZooKeeper server, using Apache Zookeeper. To run this, we have to run the ZooKeeper from a different thread. Hence, we start the ZooKeeper once we instantiate it. Following is the code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/0a557ed06b03833787c7fa8d47a3432e/href">https://medium.com/media/0a557ed06b03833787c7fa8d47a3432e/href</a></iframe><p>Next part is where I created the Kafka cluster, which is the most important part, in my opinion. Following is the code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6149a018151bef4d594ca0f8c2c1a90e/href">https://medium.com/media/6149a018151bef4d594ca0f8c2c1a90e/href</a></iframe><p>Let’s go through with the implementation of the Kafka cluster.</p><p>First, in the constructor, we initialize the Kafka cluster. We need to set the following for this.</p><ul><li>The dataDir <br>which will be used as the root directory of the ZooKeeper and the Kafka server logs.</li><li>The host <br>The host where the Kafka cluster is running. This is optional, and if it is not provided, localhost will be used.</li></ul><p>Then inside the constructor, we initialize default properties for the ZooKeeper and the Kafka server, by using the default properties files shipped with Kafka. (Note: This method will not work as shown in the gist, since it uses resource as stream to read the files. Check the original github project for working sample. Gist is only used for showing the implementation steps.)</p><p>We also create a List of brokers in the constructor. This list will keep all the brokers we create inside the cluster.</p><p>Then we have withZooKeeper() method. This method will create and run our Local ZooKeeper server. It needs the following parameters.</p><ul><li>The port<br>The client port of the ZooKeeper server, to which the ZooKeeper will listen.</li><li>The customProperties<br>Provide additional properties for the ZooKeeper server, if there are any. You can omit setting this, if the default settings are adequate.</li></ul><p>Once we call this method, the ZooKeeper will start running in a separate thread. It will create a directory named zookeeper inside the dataDir provided in the constructor.</p><p>After that, we have withBroker() method, to create a broker. This method needs the following parameters</p><ul><li>The protocol<br>This is basically the security protocol used in Kafka broker. But providing this will not set any security protocol to the broker itself. It rather uses this value to create the listener configuration of the broker. (If you want to provide the security protocol, use customProperties to set them.) As per the Kafka convention, the listener should be appended by the security protocol. Otherwise, we have to provide the listener.security.protocol.map configuration. Since we use this for testing, we don’t need to go that far.</li><li>The port<br>The port by which the Kafka server listens to the Kafka clients.</li><li>The customProperties<br>Provide additional properties for the Kafka server, if there are any. You can omit this, if the default settings are adequate, which is the case in most of the time.</li></ul><p>This method will create a broker with the given settings. This method will set the following settings additionally.<br>- A data directory named kafka inside the provided dataDir. <br>- ZooKeeper connect config using the previously created zookeeper configurations<br>- Broker ID configuration by the number of existing brokers.</p><p>After calling these methods, we can start our Kafka cluster, using the start() method. By calling the start() method, we start all the brokers we created.</p><p>Additionally we can create Kafka Consumers, or Kafka Producers to communicate with the cluster. For this, we have two additional methods.</p><p>The first one is withConsumer method. You have to create a consumer using this method in order to consume messages from the created Kafka cluster. This method requires the following parameters.</p><ul><li>The keyDeserializer</li><li>The valueDeserializer</li><li>The groupId<br>This is the group ID used for the consumer.</li><li>The topics<br>This is the list of topics to subscribe. The consumer can subscribe to one or more topics.</li></ul><p>This consumer will automatically connect to the created Kafka cluster. The connection details are handled internally. In addition to that, there are some other settings which are set automatically.</p><p>First one is that this consumer will consumer one message at a time. This is because the consumer is used in testing. Things get complicated if the consumer consumes messages in batches. Hence it is limited to single message at a time.</p><p>The next thing is the offset commit is set to the earliest. The reason behind this is that this consumer is used when the Kafka cluster is started and will be closed when the cluster is closed. There’s no point of missing any previous messages here. Hence the consumer will start to consume from the beginning.</p><p>Next method is withProducer() method. You have to create a producer using this method in order to send messages to the created Kafka cluster. This method requires the following parameters. I’m not going to explain these since they are self explanatory.</p><ul><li>The keySerializer</li><li>The valueSerializer</li></ul><p>This method will create a producer with the provided settings, but it also adds some other settings. The first thing is the Kafka broker connection settings. This setting is handled internally. Another setting is that the batch.size setting is set to 0. This means that the producer do not wait to create batches of messages, instead it sends the messages immediately.</p><p>Finally I want to mention the following additional functions in the Kafka cluster.</p><ul><li>stop()<br>Stops the Kafka cluster. This will stop the Kafka consumer, Kafka producer, Kafka server and it will delete all the log directories too.</li><li>createTopic()<br>This method can be used to create topics in our Kafka cluster. It requires topic name, number of partitions and the replication factor of the topic.</li><li>consumeMessage()<br>This will consume exactly one message at a time, and returns the String value of the message.</li><li>sendMessage()<br>There are two overloaded methods to send a message. One is to send with a key, the other is to send without a key.</li></ul><p>Hope this will help someone. Also there is a<a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-139%3A+Kafka+TestKit+library"> proposal to provide a test kit for Kafka</a>, but this is still a work on progress. Once it completed, I hope we can use it.</p><p>You can go to the repository and find out more details about the implementation. Please let me know if there are any issues, or improvement needs to be added.</p><p>Visit my blog: <a href="https://thisaru.me/thoughts/graphql-federation-with-ballerina-part-i/">https://thisaru.me/thoughts</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5d47e97fa9b1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/swlh/creating-a-local-kafka-cluster-for-testing-a-weekend-project-5d47e97fa9b1">Creating A Local Kafka Cluster for Testing: A Weekend Project</a> was originally published in <a href="https://medium.com/swlh">The Startup</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Ballerina Kafka Serialization with Avro]]></title>
            <link>https://medium.com/ballerina-techblog/ballerina-kafka-serialization-with-avro-83126a7df9a1?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/83126a7df9a1</guid>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[apache-kafka]]></category>
            <category><![CDATA[avro]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 05 May 2020 23:14:21 GMT</pubDate>
            <atom:updated>2023-08-02T06:21:48.001Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This feature is now deprecated in Ballerina SwanLake</blockquote><p><a href="https://kafka.apache.org/"><em>Apache Kafka</em></a> is widely-used message streaming platform to handle real-time messaging in network applications. <a href="https://ballerina.io/"><em>Ballerina</em></a> on the other hand is a new programming language, which mainly focused on network applications.</p><p>Ballerina language comes with a handy set of libraries (or modules if you speak ballerina) to help to create cloud-era applications easily. The <a href="https://ballerina.io/learn/api-docs/ballerina/kafka/index.html"><em>Ballerina Kafka module</em></a> is such a module to easily handle Kafka messages in Ballerina applications.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zm95u6OhP0XKFIqf6XZYuw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/820/1*Zaun06N_MAA36GQiinRR8Q.png" /></figure><p><a href="https://avro.apache.org/"><em>Apache Avro</em></a><em> </em>is a data serialization system and it is frequently used in Kafka messaging as the serializing / deserializing system.</p><p>This article will demonstrate how to use Apache Avro to serialize / deserialize the messages in Ballerina Kafka producers and consumers.</p><blockquote>You can find the source code used in this article on Github. <a href="https://github.com/ThisaruGuruge/ballerina-kafka-avro-sample">Check it out</a>.</blockquote><p>First, let’s setup our environment. If you already know how to install ballerina, configure Kafka, and configure a Schema registry for Kafka, you can skip these steps.</p><h3>Configure The Environment</h3><ul><li>Download and install Ballerina:<br>First you need to download and install ballerina. You can easily download it from <a href="https://ballerina.io/downloads/">ballerina website</a>. For this article, I am using the ballerina 1.2.3 version. Any Ballerina 1.2.x version should work fine.</li><li>Download Kafka:<br>You need to download and run Kafka server instance to make this work. Apache Kafka can be downloaded from <a href="https://kafka.apache.org/downloads">Kafka website</a>. For this article, I am using Kafka 2.3.1, but any of the Kafka 1.x and 2.x versions should work fine.</li><li>Download Confluent (For schema registry)<br>To use Avro serialization, we need a schema registry. Confluent provides a schema registry for Kafka. Confluent can be downloaded from <a href="https://www.confluent.io/download/">Confluent website</a>. I am using confluent 5.5.0 for this article. But confluent 5.4.x will also work fine.</li><li>Start the Zookeeper<br>Open a terminal and go inside the downloaded Kafka Directory. Then enter the following command to start the zookeeper.</li></ul><pre>bin/zookeeper-server-start.sh config/zookeeper.properties</pre><ul><li>Start the Kafka Server<br>Open another terminal and go inside the downloaded Kafka directory. Then enter the following command to start the Kafka server.</li></ul><pre>bin/kafka-server-start.sh config/server.properties</pre><ul><li>Start the Schema Registry<br>Open another terminal and go inside the dowloaded Confluent directory. Then enter the following commands to start the Schema Registry.</li></ul><pre>bin/schema-registry-start etc/schema-registry/schema-registry.properties</pre><ul><li>A code editor<br>You can use any code editor for this, I am using VSCode since VSCode has a pretty decent Ballerina plugin. You may use IntelliJ IDEA as well.</li></ul><h3>Creating A Ballerina Project</h3><p>We are going to create a ballerina project with two modules. One module is for the producer, and the other is for the consumer.</p><p>To create the ballerina project, open a terminal and type the following:</p><pre>ballerina new kafka_avro_sample</pre><p>This will create a new Ballerina project. Now go inside the kafka_avro_sample directory and enter the following two commands:</p><pre>ballerina add producer<br>ballerina add consumer</pre><p>This will create two modules inside our ballerina project. The modules include resources, and tests directories as well as a Module.md file. For this article, I am going to remove the files and directories, which aren’t compulsory for the project to work, to reduce the complexity. If you want to know more about the ballerina project structure, read about <a href="https://ballerina.io/learn/how-to-structure-ballerina-code/">how to structure ballerina code</a>.</p><pre>├── Ballerina.toml<br>└── src<br>    ├── consumer<br>    │   └── main.bal<br>    └── producer<br>        └── main.bal</pre><p>Now this looks much simple.</p><h3>Adding The Dependencies</h3><p>To run Ballerina Kafka clients with Avro, we need to add some dependencies. To do so, let’s first create a directory inside our project called javalibs to keep our dependencies.</p><pre>mkdir javalibs</pre><p>We need following dependencies to run the producer</p><ul><li>io.confluent:kafka-avro-serializer:5.4.1</li><li>io.confluent:kafka-schema-registry-client:5.4.1</li><li>io.confluent:common-config:5.4.1</li><li>io.confluent:common-utils:5.4.1</li><li>org.apache.avro:avro:1.9.2</li><li>com.fasterxml.jackson.core:jackson-core:2.10.3</li><li>com.fasterxml.jackson.core:jackson-databind:2.10.3</li><li>com.fasterxml.jackson.core:jackson-annotations:2.10.3</li></ul><p>You need to download the corresponding jar files and copy them to the previously created javalibs directory. The mentioned versions are the ones used for this article. You may use different versions.</p><p>Now we have to mention the dependencies in our Ballerina.toml file. Following is a sample dependency entry in the Ballerina.toml file. To learn more about adding Java dependencies in Ballerina, please read <a href="https://ballerina.io/learn/how-to-call-java-code-from-ballerina/">How to Call Java Code from Ballerina</a>. Following is an example dependency entry in the Ballerina.toml file.</p><pre>[platform]<br>target = &quot;java8&quot;</pre><pre>[[platform.libraries]]<br>    module = &quot;producer&quot;<br>    path = &quot;./javalibs/kafka-avro-serializer-5.4.1.jar&quot;<br>    artifactId = &quot;kafka-avro-serializer&quot;<br>    version = &quot;5.4.1&quot;<br>    groupId = &quot;io.confluent&quot;</pre><h3>Creating The Producer</h3><p>Now we can create our producer. To create the producer, open the src/producer/main.bal file in your editor.</p><p>You need to import the ballerina/kafka module first.</p><pre>import ballerina/kafka;</pre><p>Now we have to set the necessary properties of the producer. For this, Ballerina Kafka module have a record type called kafka:ProducerConfiguration.</p><pre>kafka:ProducerConfiguration producerConfiguration = {<br>    bootstrapServers: “localhost:9092”,<br>    valueSerializerType: kafka:SER_AVRO,<br>    schemaRegistryUrl: “http://localhost:8081&quot;<br>};</pre><p>Here, first we mention the Kafka server host and the port in bootstrapServers field.</p><p>Then we provide the serializer type. You can have valueSerializerType, and the keySerializerType for your Kafka messages. Here, I only use valueSerializerType. Since we do not specifically mention the keySerializerType, its value will be kafka:SER_BYTE_ARRAY which is the default value for both the keySerializerType and the valueSerializerType. By setting the valueSerializerType to kafka:SER_AVRO we set the Apache Avro as the serializer for the Kafka values.</p><p>Then we provide schemaRegistryUrl, which is we set in early steps. Since we use the default configurations for confluent, the schema registry URL will be http:localhost:8081.</p><p>Then we can create out Producer object as below:</p><pre>kafka:Producer producer = new(producerConfiguration);</pre><p>To demonstrate the serialization, I am defining two record types:</p><pre>public type Account record {<br>    int accountNumber;<br>    float balance;<br>};</pre><pre>public type Person record {<br>    string name;<br>    int age;<br>    Account account;<br>};</pre><p>In order to serialize these records, we need a schema. I am defining the schema here inside the code for ease. You can use a separate file and read it.</p><pre><em>string</em> schema = &quot;{\&quot;type\&quot; : \&quot;record\&quot;,&quot; +<br>  &quot;\&quot;namespace\&quot; : \&quot;Thisaru\&quot;,&quot; +<br>  &quot;\&quot;name\&quot; : \&quot;person\&quot;,&quot; +<br>  &quot;\&quot;fields\&quot; : [&quot; +<br>  &quot;{ \&quot;name\&quot; : \&quot;name\&quot;, \&quot;type\&quot; : \&quot;string\&quot; },&quot; +<br>    &quot;{ \&quot;name\&quot; : \&quot;age\&quot;, \&quot;type\&quot; : \&quot;int\&quot; },&quot; +<br>    &quot;{ \&quot;name\&quot; : \&quot;account\&quot;,&quot; +<br>    &quot;\&quot;type\&quot; : {&quot; +<br>      &quot;\&quot;type\&quot; : \&quot;record\&quot;,&quot; +<br>      &quot;\&quot;name\&quot; : \&quot;account\&quot;,&quot; +<br>      &quot;\&quot;fields\&quot; : [&quot; +<br>        &quot;{ \&quot;name\&quot; : \&quot;accountNumber\&quot;, \&quot;type\&quot; : \&quot;int\&quot; },&quot; +<br>        &quot;{ \&quot;name\&quot; : \&quot;balance\&quot;, \&quot;type\&quot; : \&quot;double\&quot; }&quot; +<br>      &quot;]}&quot; +<br>    &quot;}&quot; +<br>  &quot;]}&quot;;</pre><p>Now we create example Person record to send using Kafka.</p><pre>Account account = {<br>    accountNumber: 19930808,<br>    balance: 123.23<br>};</pre><pre>Person person = {<br>    name: &quot;Lahiru Perera&quot;,<br>    age: 28,<br>    account: account<br>};</pre><p>To send this record, we need to create a kafka:AvroRecord. This record consists two fields, schemaString, which is a string, to provide the Avro schema, and the dataRecord, which is the type of anydata to provide the record to serialize. We can create it as below.</p><pre>kafka:AvroRecord avroRecord = {<br>    schemaString: schema,<br>    dataRecord: person<br>};</pre><p>Now we can send the message using send() function in kafka:Producer.</p><pre>var result = producer-&gt;send(avroRecord, &quot;add-person-with-account&quot;);</pre><p>Following is the complete code for the producer.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/82f1a7adc514db2cd66ba2ef3db6b31f/href">https://medium.com/media/82f1a7adc514db2cd66ba2ef3db6b31f/href</a></iframe><h3>Creating The Consumer</h3><p>Now we are going to create a consumer to consume Kafka messages, using Avro deserialization. First open the src/consumer/main.bal file in your editor.</p><p>We have to import balleina/kafka in here too.</p><pre>import ballerina/kafka;</pre><p>Now we can provide necessary properties for the Consumer. Following is the minimum required values for the consumer to use Avro deserialization.</p><pre>kafka:ConsumerConfiguration consumerConfiguration = {<br>    bootstrapServers: &quot;localhost:9092&quot;,<br>    groupId: &quot;avro-consumer-group&quot;,<br>    topics: [&quot;add-person-with-account&quot;],<br>    valueDeserializerType: kafka:DES_AVRO,<br>    schemaRegistryUrl: &quot;http://localhost:8081/&quot;<br>};</pre><p>Then we can create a listener using these configurations.</p><pre>listener kafka:Consumer consumer = new(consumerConfiguration);</pre><p>Now, we can create a service on the above created listener. Inside the service, we have our resource function onMessage, which is the resource function required to consume Kafka messages inside a service.</p><pre>service KafkaService on consumer {<br>    resource function onMessage(<em>kafka:Consumer</em> <em>consumer</em>, <em>kafka:ConsumerRecord</em>[] <em>records</em>) {<br>        foreach <em>var</em> kafkaRecord in records {<br>            <em>anydata</em> value = kafkaRecord.value;<br>            if (value is kafka:AvroGenericRecord) {<br>                log:printInfo(value.toString());<br>            } else {<br>                log:printError(&quot;Invalid record type received.&quot;);<br>            }<br>        }<br>    }<br>}</pre><p>Whenever new message(s) pushed to the subscribed topics of the consumer, the onMessage resource will be dispatched. Then we can iterate through the received records using the foreach loop.</p><p>The value field of the kafka:ConsumerRecord holds the deserialized value of the received message.</p><blockquote>Note that the Ballerina Kafka Consumers only supports generic Avro record deserialization yet. Therefore, you have to read the fields by their name.</blockquote><p>Following is the complete code for the consumer.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/abc3773a620e7a29523d84004a462857/href">https://medium.com/media/abc3773a620e7a29523d84004a462857/href</a></iframe><h3>Running The Project</h3><p>Now we have completed the implementation, we can run the project. Make sure your Kafka server, and the Schema Registry is up and running.</p><p>To run the project, open a terminal window and go inside our project directory (kafka_avro_sample). We first run our consumer. To run it enter the following command in the terminal.</p><pre>ballerina run consumer</pre><p>This will start the consumer. If the consumer started without any issue, following lines will be printed in the terminal. Let it run in that terminal.</p><pre>[ballerina/kafka] kafka servers: localhost:9092<br>[ballerina/kafka] subscribed topics: add-person-with-account<br>[ballerina/kafka] started kafka listener</pre><p>Then we can run our producer. To do so, open another terminal, and enter the following command.</p><pre>ballerina run producer</pre><p>This will run our producer. If the producer was able to send the message successfully, the following line will be printed in the terminal.</p><pre>Successfuly sent</pre><p>Now, if you check the terminal where we ran our consumer, something similar to the following lines should be printed.</p><pre>2020-05-06 18:44:26,671 INFO  [thisaru/consumer] - name=Lahiru Perera age=28 accountNumber=19930808 balance=123.23</pre><p>That’s it! We successfully sent a message using Kafka with Avro serialization and received it back.</p><p>Hope you learned something from this.</p><blockquote>Note: Apache Kafka and Ballerina logos are trademarks of the respective companies.</blockquote><p>The complete project can be found as a <a href="https://github.com/ThisaruGuruge/ballerina-kafka-avro-sample">Github project</a>. Feel free to check it out.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=83126a7df9a1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/ballerina-kafka-serialization-with-avro-83126a7df9a1">Ballerina Kafka Serialization with Avro</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Simple Review Filtering System Using Ballerina Kafka]]></title>
            <link>https://medium.com/ballerina-techblog/building-a-simple-review-filtering-system-using-ballerina-kafka-42cee518ecef?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/42cee518ecef</guid>
            <category><![CDATA[kafka]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[messaging]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 12 Feb 2019 21:22:58 GMT</pubDate>
            <atom:updated>2019-02-15T08:42:10.445Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZfNTZkP8DXXCN2_lfTW7PQ.jpeg" /></figure><p>Previously I explained about <a href="https://medium.com/ballerina-techblog/get-along-with-ballerina-kafka-754c28de685c"><em>how to configure Ballerina-Kafka</em></a> module to work along with Apache Kafka. Now let’s see how to implement a simple review filtering system using Ballerina and Kafka.</p><blockquote>If you’re not familiar with Ballerina, please take a look at <a href="https://ballerina.io/learn/">ballerina language </a>first, before continuing.</blockquote><p>Consider the following scenario:</p><p>Develop a system where you have to get reviews about online courses in an online educational website, and then decide whether are there any fraudulent reviews. If there are any, filter them out, and send your *<em>honest</em>* reviews to another place.</p><p>Kafka and Ballerina suits this scenario really well.</p><p>First what we need to do is to setup an endpoint where we take all the reviews. Using ballerina, you can easily do this.</p><h3>Create the System to Filter Reviews</h3><p>Following is the design of the application we’re going to build.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3FgFZ6ZfyqA8PC9soHtAmg.png" /></figure><ul><li>We have a Kafka broker, which is handling all the messages.</li><li>PreProcessReviews : This is the application to retrieve and pre-process the reviews. All the reviews are directed here, through a web service. We retrieve those reviews (in JSON format) and publish them to a Kafka topic pre-processed-reviews , so that others can get them.</li><li>FilterReviews : This is where we filter-out reviews. We decide whether a review is a fraudulent one, or not. Depending on the decision, we send the review into two different topics; accepted-reviews or rejected-reviews.</li><li>HandleAcceptedReviews/ HandleRejectedReviews : These two endpoints handle those accepted or rejected reviews.</li></ul><p>In this sample I am not going to tell you how to decide a review is fraudulent or not. We’re just looking at how we can use Kafka and Ballerina together to develop a system to filter the reviews.</p><p>Following is our directory structure:</p><pre>.<br>├── README.md<br>└── src<br>    └── ballerina<br>        ├── FilterReviews<br>        │   └── FilterReviews.bal<br>        ├── PreProcessReviews<br>            └── PreProcessReviews.bal</pre><p>We create a directory for each of out component, and inside the directory we create our .bal files. After creating this structure, inside the src/ballerina directory, execute the following command:</p><pre>ballerina init</pre><p>This will initialize a ballerina project in your area.</p><p>Now let’s create PreProcessReviews.bal component:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/30ded5ff06e950f3c4f2dae3b247799e/href">https://medium.com/media/30ded5ff06e950f3c4f2dae3b247799e/href</a></iframe><p>First we create a Kafka Producer using some cofigurations. Let’s look into those configurations</p><ul><li>bootstrapServers: This configuration parameter sets the Kafka broker addresses, to which the producer should send the data.</li></ul><blockquote>You can use more than one Kafka brokers for a producer. If there are multiple brokers, use following syntax in your configuration: “bootstrapServers: host1:port1, host2:port2”</blockquote><ul><li>clientID: This configuration parameter is used for identifying the producer. This should be unique.</li><li>asks: This configuration denotes the number of acknowledgments the producer requires the leader to have received before considering a request complete.</li><li>noRetires: This configuration parameter sets the number of times which the producer retires to send a message, if sending is failed.</li></ul><blockquote>To see all the available configurations for a Ballerina Kafka Producer, please refer the API doc for wso2-kafka-module.</blockquote><p>Then we create an HTTP service, which listens to the port 30005. Inside the service we read the request (which sends the reviews) and process the reviews.</p><blockquote>Make sure to handle the errors, as ballerina is intended to do so. For the example, I have ignored some of the resulting variables (using _ = ) which is not a good practice.</blockquote><p>As you can see we have two record types; Review and ProcessedReview. The reviews we get from our request should be matched to the record type Review while, we create ProcessedReview type from the review we receive, and the isFraud status of the Review. You can add isFraud flag after deciding whether a given Review is fraudulent or not. Then we convert the ProcessedReview into byte array, then send it to the Kafka Producer.</p><p>producer-&gt;send() function returns an error if the sending is failed, it returns nil otherwise.</p><p>Now let’s create our FilterReviews component:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/436b0c04faa45e8db8a38cee4ca930e2/href">https://medium.com/media/436b0c04faa45e8db8a38cee4ca930e2/href</a></iframe><p>Here we have both, a Kafka Consumer and a Kafka Producer.</p><p>First we define the configurations for the Kafka Consumer using the configurations shown in the code above. Here in Consumer configurations, we define the following configurations:</p><ul><li>bootstrapServers: Host and port number of the Kafka brokers which the consumer should connect. As we mentioned in Kafka Producer configurations, Consumer configurations too can have multiple brokers, to add multiple brokers, just provide them comma separated (eg: bootstrapServers: &quot;host1: port1, host2:port2&quot;), as we did in Producer config.</li><li>groupId: This group ID is used to identify different consumer groups in kafka cluster. This is helpful when we need Kafka group management functionality is been used.</li><li>topics: This configuration holds the array of topics to which the Consumer should listen. You can provide multiple topics as an array of strings.</li></ul><blockquote>To see all the available configurations for a Ballerina Kafka Consumer, please refer the API doc for wso2-kafka-module.</blockquote><p>I just said, Kafka Consumer can *listen* to particular topics! What is *listening* to a topic ? How can a Consumer *listen* to a Topic ?</p><p>Well, Kafka Consumer can be used as a listener in Ballerina. (<em>This listener model is a common practice in ballerina, which is really handy.</em>). Using this listener approach you can *listen* to a given Kafka topic, and whenever someone publishes to that particular topic, our listener will retrieve the values. For the purpose all you need to do is to define Kafka Consumer as a listener type.</p><p>All we have to do is to create a listener with topics to which it should listen, and create a service on that listener object.</p><pre>service filterReviewService on reviewConsumer {<br>    onMessage(<br>            kafka:SimpleConsumer consumer<strong>,<br>            </strong>kafka:ConsumerRecord[] records<br>    ) {<br>        // Logic to process the review<br>    }<br>}</pre><p>This service (created on Kafka Consumer), have only one resource function, either</p><pre>onMessage(<br>    kafka:SimpleConsumer consumer<strong>,<br>    </strong>kafka:ConsumerRecord[] records<br>) {<br>    // Logic to process reviews.<br>}</pre><p>or more complex resource signature:</p><pre><strong>resource function </strong>onMessage(<br>    kafka:SimpleConsumer consumer<strong>,<br>    </strong>kafka:ConsumerRecord[] records<strong>,<br>    </strong>kafka:PartitionOffset[] offsets<strong>,<br>    string </strong>groupId<br>) {<br>    // Logic to process the review.<br>}</pre><blockquote>Note that the onMessage() resource can return either error , nil () or union of both these types, error?. If your onMessage function do return something else, there will be a compilation error.</blockquote><p>If the resource name is wrong or the function signature is invalid, there will be a compilation error.</p><p>ConsumerRecord[] is passed into the resource function, which will provide the array of records, which our listener retrieved. Then we can handle the received review and publish them into two different topics, rejected-reviews and accepted-reviews. (Not going to explain about the Producer again).</p><p>We can categorize the Reviews and send them two different topics, to handle after that. We use our producer to do so. Producer will send the review to either accepted-reviews or rejected-reviews depending on the status of the review.</p><p>That’s it !</p><p>This is a smaller example to show how to work with Ballerina Kafka. If you have any problem (regarding the Ballerina Kafka), feel free to ask. You can catch me on Twitter.</p><blockquote>Let’s see how we can play more with Kafka offsets, and committing records in next posts.</blockquote><blockquote>Note: Apache Kafka and Ballerina logos are trademarks of the respective companies.</blockquote><p><a href="https://twitter.com/ThisaruGuruge">JavaScript is not available.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=42cee518ecef" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/building-a-simple-review-filtering-system-using-ballerina-kafka-42cee518ecef">Building a Simple Review Filtering System Using Ballerina Kafka</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Getting Started with Ballerina Kafka]]></title>
            <link>https://medium.com/ballerina-techblog/get-along-with-ballerina-kafka-754c28de685c?source=rss-ce30d56b8733------2</link>
            <guid isPermaLink="false">https://medium.com/p/754c28de685c</guid>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[ballerinalang]]></category>
            <category><![CDATA[ballerina]]></category>
            <category><![CDATA[apache-kafka]]></category>
            <category><![CDATA[kafka]]></category>
            <dc:creator><![CDATA[Thisaru Guruge]]></dc:creator>
            <pubDate>Tue, 05 Feb 2019 21:48:09 GMT</pubDate>
            <atom:updated>2020-03-05T15:09:34.165Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>Ballerina is now ships with Kafka module! This setup is no more needed!</blockquote><p><a href="https://www.ballerina.io/">Ballerina</a> is a rising, cloud-native programming language. Even though there are many languages out there, ballerina is one of a kind.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZfNTZkP8DXXCN2_lfTW7PQ.jpeg" /></figure><p><a href="https://kafka.apache.org/">Kafka</a>, on the other hand is a rising, well-used distributed streaming platform. It is widely used in messaging domain nowadays.</p><p>Now, what is <strong><em>WSO2 Ballerina Kafka </em></strong>?</p><p>The WSO2 Kafka module is the set of Ballerina APIs for using apache Kafka. If you’re developing a system, which uses Kafka as your messaging platform, and you’re thinking of developing the system using Ballerina, here’s what you need !</p><blockquote>If you’re new to <a href="https://www.ballerina.io/">Ballerina</a>, please take sometime to learn about Ballerina, before reading this any further. Ballerina has a vast range of <a href="https://ballerina.io/learn/by-example/">ballerina examples</a> to start with. You can find the <a href="https://ballerina.io/learn/api-docs/ballerina/http.html">Ballerina API Documentation here</a>.</blockquote><p>wso2-kafka module provides user a range of APIs. You can make a Kafka Producer using Ballerina, and can publish to a Kafka topic right away! Or you can create a Kafka Consumer, subscribe it to a topic and retrieve data.</p><p>But the best part is, the Service model !</p><p>Ballerina is using service-listener model, in almost all their libraries; wso2-kafka is no exception. You can create a Kafka Listener using wso2-kafka module, and listen to certain Kafka topic(s). When someone publishes to a topic to which a Listener is listening, it will retrieve those data, right away!</p><p>There are many use cases we can consider using wso2-kafka module. But first of all, I am going to explain how to setup wso2-kafka module to function correctly.</p><h3>Setting up the Environment</h3><p>First of all, you need to <strong>download Ballerina distribution</strong>. The latest version as of the day this is written is Ballerina V0.990.2. You can<em> </em><a href="https://ballerina.io/downloads/"><em>download ballerina from here</em></a>.</p><p>Then you need to <strong>download Apache Kafka</strong>, V1.0.0 or higher. (Ballerina Kafka connector supports to Kafka Versions 1.x and 2.0.x as of now.). You can <a href="https://kafka.apache.org/downloads"><em>download the Apache Kafka from here</em></a>.</p><p>Once you download these two, you have to <strong>download wso2-kafka connector.</strong> You can <a href="https://github.com/wso2-ballerina/module-kafka/releases"><em>download wso2-kafka connector from here</em></a>. After downloading you can install your wso2-kafka module using following ways:</p><h4>Method 1: Using installation scripts</h4><p>Unzip the <strong>wso2-kafka-&lt;<em>version</em>&gt;.zip</strong> and go into the extracted directory. Inside that directory you can find two scripts:install.sh and install.bat. Use the one compatible with you ( install.sh for Linux and Mac, install.bat for windows.)</p><p>Provide the <em>BALLERINA_HOME</em> location (which you downloaded before) when asked. This will automatically install wso2-kafka module to your ballerina distribution.</p><p>If your installation is successful, following message will appear in your terminal.</p><pre>Please enter Ballerina home: &lt;<em>YOUR_BALLERINA_HOME</em>&gt;<br>Successfully installed Kafka module!</pre><h4>Method 2: Manually Installing Ballerina Kafka Module</h4><p>Unzip the <strong>wso2-kafka-&lt;<em>version</em>&gt;.zip</strong> and go into the extracted directory. Then copy the balo/wso2/kafka directory, into the &lt;BALLERINA_HOME&gt;/lib/repo/wso2/ directory. Now you should have a directory named kafka inside the &lt;BALLERINA_HOME&gt;/lib/repo/wso2/ directory.</p><p>Then go back to the wso2-kafka directory, and copy dependencies/wso2-kafka-module-&lt;version&gt;.jar file into &lt;BALLERINA_HOME&gt;/bre/lib/ directory.</p><p>From either of aforementioned methods, you are installing wso2-kafka module into your Ballerina distribution. Now we’re all set for developing our application.</p><h3>Uninstalling WSO2-Kafka Module from Ballerina</h3><p>If you want to uninstall wso2-kafka module, there are two methods, as similar to the installation methods, mentioned above.</p><h4>Method 1: Using Uninstallation Scripts</h4><p>Go inside your wso2-kafka directory. There are two uninstall scripts; uninstall.sh and uninstall.bat. If you’re a Linux or a Mac user, use uninstall.sh. If you’re a Windows user, use uninstall.bat. Provide the correct <em>BALLERINA_HOME </em>when asked.</p><p>If the uninstallation is successful, your command prompt will show the following message:</p><pre>Enter Ballerina home: &lt;<em>YOUR_BALLERINA_HOME</em>&gt;<br>Successfully uninstalled Kafka module!</pre><h4>Method 2: Manually Removing Ballerina Kafka Module</h4><p>You can manually uninstall wso2-kafka module. To do so, delete the following file:</p><p>&lt;<em>BALLERINA_HOME</em>&gt;/bre/lib/wso2-kafka-&lt;<em>version</em>&gt;.jar</p><p>You also have to delete the following directory:</p><p>&lt;<em>BALLERINA_HOME</em>&gt;/lib/repo/wso2/kafka</p><p>Now the wso2-kafka module is successfully uninstalled.</p><p>Note: You can’t have two wso2-kafka versions in the same time. If you didn&#39;t uninstall the kafka module, before installing the newer version, it might cause you problems.</p><blockquote><a href="https://medium.com/ballerina-techblog/building-a-simple-review-filtering-system-using-ballerina-kafka-42cee518ecef">In our next article</a>, let’s see how to implement a sample review filtering system using wso2-kafka.</blockquote><blockquote>Note: Apache Kafka and Ballerina logos are trademarks of the respective companies.</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=754c28de685c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/ballerina-techblog/get-along-with-ballerina-kafka-754c28de685c">Getting Started with Ballerina Kafka</a> was originally published in <a href="https://medium.com/ballerina-techblog">Ballerina Swan Lake Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>