DEV Community: Héctor Valls

Push vs Polling vs Long Polling

Héctor Valls — Tue, 03 Aug 2021 08:43:44 +0000

Sometimes, we need to build "event-based" applications like a chat, an app showing the current price of a crypto currency or an event-driven microservices architecture, for example. In these cases, we have to decide what communication model fits better in terms of performance and scalability for an specific use case. Basically, we have three models: push, polling and long polling. Let's see the conceptual differences between them.

Push

In this model, client opens a connection to the server and waits for messages. The connection is kept open and server pushes messages synchronously to the client when it receives them.

This model is the most "real-time" one of the three: messages goes to the client as soon as they are received by the server. And, precisely because of that, it is not the most scalable one. Server does not know if client is ready to consume new messages and may become busy, slowing down the server.

Pushing model is appropriate when you have limited clients/consumers and messages. For example, a chat application like Whatsapp where there are few clients per group or "channel" (in fact, WhatsApp uses this model). RabbitMQ and Redis Pub/Sub are some technologies using push model.

Polling

Unlike pushing, polling is a request/response model. Client makes a request to the server and gets a response from it immediately with a new message or without any.
This model is a waste of bandwith when there are no new messages and responses contain no data. Also, open and close connections is expensive. Although this model does not scale well, it is the easiest one to implement and could be useful is some scenarios where scalability and performance is not a concern at all.

Long polling

This one is a combination of the two previous models: client makes a request to the server, but this is kept open until a "useful" response is returned. What do I mean with "useful" response? Well, problem with polling are empty responses, wasting bandwidth and server resources. With long polling, client tells the server "Hey, reply to me when there is some new message, I will wait for that". This way, server knows that specific client is ready to receive messages and can send them to it.

Two interesting things here. Once response is returned, client/server connection is closed and client is responsible of make another request to the server when it's ready to handle new messages. Besides, client can provide extra information to the server to achieve a better performance: for instance, it could tells the server "Hey, reply to me when there are three new messages or when the pending messages are 25Kb or more". This way, message handling is optimised and client/server communication is more efficient. Internally, this model could be implemented as a server-side local-polling model.

Kafka is an example of technology implementing long polling model, and that's the reason why it is more scalable compared with RabbitMQ when there is a massive amount of messages and clients. Also, it's worth to mention that Server Sent Events (SSE) is a protocol that implements long polling model, with the difference that it does not close the connection after a message is sent to the client, but it is kept open.

As you saw, I didn't mention any protocol or specific technology to implement these three patterns because, actually, they are protocol agnostic.

I hope you enjoyed the post!

API documentation in event driven applications

Héctor Valls — Sat, 02 May 2020 17:53:15 +0000

We live in the era of the distributed systems. Airlines and hotels communicate each other to offer us a better experience in our travels; shops work with shipping companies so we have our new products in our homes in a matter of hours. All of these integrations across services are done using APIs. Those APIs must be well documented so the consumers can integrate with them easily. This is not only a technical matter but also a business related one.

Currently, the most used API protocols are REST and GraphQL. You can document your REST API using OpenAPI initiative. In the case of GraphQL, you can use tools like GraphiQL, which makes supported operations visible through introspection query.

Both protocols are essentially synchronous: you make a request against the API and wait for a response. But what happens when you are to design an asynchronous event oriented API? OpenAPI has been designed to document request/response APIs and GraphQL has its own specific mechanism so they are not applicable in this case. AsyncAPI to the rescue.

Let's imagine you work on a book shopping website called SuperFunnyBooks. Your team is responsible of the Catalog Service. Book publishers can register new books to the platform through your service.

SuperFunnyBooks product team needs a new feature to be added: when a new book is registered on the platform, it has to be recommended to users interested in that genre. To do this, a brand new service, Recommendation Service, is created and a new team is assigned to.

The new service needs to know when a new book is registered in the platform, so Catalog Service will publish a BookRegistered event to a message queue every time this happens. This event will contain information about the new book. But, where is located that message queue? and what does exactly "information about the new book" mean? It sounds a little bit abstract and vague. Recommendation Service team needs to know every single field is going to be included in the event's payload, as well as how to connect to the message queue to start listening for new events. In other words, they need the API documentation.

This is how this event oriented API would look like with AsyncAPI:

asyncapi: 2.0.0
info:
  title: Catalog Service
  version: '1.0.0'

servers:
  production:
    url: catalog.superfunnybooks.com:9092
    protocol: kafka
    description: Production Kafka 

channels:
  book/registered:
    description: Book Registered Topic
    subscribe:
      summary: Receive information about new book registered in catalog
      message:
        name: BookRegistered
        contentType: application/json
        payload:
          type: object
          properties:
            bookId:
              type: string
            title:
              type: string
            author:
              type: string
            genre:
              type: string
            publisherId:
              type: string
            registeredAt:
              type: string
              format: datetime

The first part contains API metadata information. Then, server information is declared; in this case, there is a Kafka server running on catalog.superfunnybooks.com at port 9092. channels object groups all the operations that the API supports. This one allows consumers to subscribe to book/registered channel to be notified when a new book is registered. Also, the concrete event's payload schema is defined.

With this document, API is properly defined and it provides a contract between Catalog Service and its consumers. Now, Recommendation Service knows where the message queue is located in the network and how exactly an event's payload looks like.

To sum up, having a nice API documentation improves communication between teams in a company as well as between external stakeholders. Also, using a machine-friendly format (like YAML) in an API documentation enables it to be integrated in the development lifecycle and the possibility of taking advantage of techniques like server stubbing or automatic testing.

This has been a simple example of how to use AsyncAPI specification to document event oriented APIs. AsyncAPI spec provides a lot of options that allow to define clearly many aspects of an API. It is worth keeping it in mind.

I hope you enjoyed this post!

GraphQL for server-side resource aggregation

Héctor Valls — Thu, 12 Mar 2020 19:44:40 +0000

When implementing service oriented and microservices architectures, sooner or later, the aggregation of data coming from different services becomes a problem to face. In this post, we will see how GraphQL can help with this.

(A basic knowledge of GraphQL is required. You can learn GraphQL basics on the official website).

We are developing a property rental API, and the consumer needs an endpoint to fetch information about a property and its landlord. An example response would look like this:

GET /properties/1234

{
    id: 1234,
    address: "10 Downing Street",
    area: 90,
    landlord: {
        id: 882,
        name: "John Doe"
        email: "john.doe@mail.com"
    }
}

We can see two aggregates involved in this piece of information: Property and Landlord.

In a monolithic application, we would write a query, with some SQL JOIN maybe, to fetch the data from a database, and marshall it to the above JSON.

However, let's assume in our rental organization we have a microservices architecture; we have a Property Microservice and Landlord Microservice, with a database for each one. For that reason, we can't just JOIN two database tables; integration between services is made across the network and not through database sharing.

We need an API Gateway or BFF to aggregate data from both services and serve it to the API consumer.

We could perform aggregation "by hand":

//This code belongs to API Gateway / BFF
fun getProperty(id: Int) : JsonObject {
    val property = propertyService.getById(id)
    val landlord = landlordService.getById(property.landlordId)
    return buildJson(property, landlord)
}

Note that property object, fetched from propertyService::getById, does not contain information about its landlord, but only its identifier; landlordId. We use that field to fetch the whole landlord info, through landlordService, and construct the full response JsonObject.

When implementing this approach, due to its stream-based nature, reactive programming tools like ReactiveX are quite useful.

An alternative to this, is letting GraphQL engine do the job.

Resource aggregation using GraphQL

First, we are going to define the GraphQL schema:

type Query {
  getProperty(id: String!): Property
}

type Property {
  id: String
  address: String
  area: Int
  landlord: Landlord
}

type Landlord {
  id: String
  name: String
  email: String
}

Now, we have to define a data fetcher for getProperty operation:

fun getPropertyDataFetcher() : DataFetcher {
  return DataFetcher { env -> {
     val propertyId = env.getArgument("id")
     return propertyService.getProperty(propertyId)
  }
}

So far, we have the information about the property. Now, we need to implement the data fetcher for its landlord:

fun getLandlordDataFetcher() : DataFetcher {
  return DataFetcher { env -> {
     val property = env.getSource<Property>()
     val landlordId = property.landlordId
     return landlordService.getLandlord(landlordId)
  }
}

With the schema and the fetchers, we are ready to build our GraphQL instance and make the query:

val graphQL = buildGraphQLFromSchemaAndFetchers()
executeQuery(graphQL, """{ query:
  getProperty(id: 1234) {
    id
    address
    area
    landlord {
      id
      name
      email
    }
  }
}""")

With this approach, we delegate the logic of the data composition to GraphQL library implementation, this way being less error-prone than doing it manually.

It looks like a declarative way; you tell it how to fetch properties, and how to fetch landlords. Then, just ask for the data you need and data aggregation is managed by GraphQL.

Sometimes, we tend to think of GraphQL just as a type of HTTP API; an alternative to REST.
This is true, but using GraphQL does not mean starting a GraphQL server. You don't need to expose an API of this type at all, depending on the use case you are trying to solve.

In this example, I have shown how to use GraphQL as a query engine and data aggregator, but I haven't mentioned anything about GraphQL servers.

Let's consider this code, that could be written using some modern REST tool:

@GET
fun getProperty(@PathParam("id") id: String) : Property {
  val property = executeQuery(graphQL, """{ query:
    getProperty(id: $id) {
      id
      address
      area
      landlord {
        id
        name
        email
      }
    }
  }""")
  return property
}

This is a REST API resource, but, under-the-hood, a GraphQL engine is responsible for aggregation of data from several sources. There is no need to run any GraphQL server.

There are many reasons you may not want to expose a pure GraphQL API. e.g. hard integration with frontend or other services, maintain compatibility, lack of GraphQL knowledge amongst the developers, or even organizational convention. Anyway, you can take advantage of GraphQL power and use it as a query engine, like we have just seen above.

I hope you enjoyed the article!