Chapter 8. Building Microservices for Helping Hands

 

"It's not the ideas; it's design, implementation and hard work that make the difference."

- Michael Abrash

Identifying bounded context is the first step towards building a successful microservices-based architecture. Designing for scale and implementing them with the right technology stack is the next and the most crucial step in building a microservices-based application. This chapter brings together all the design decisions taken in the first part of the book (Chapter 2, Microservices Architecture and Chapter 3, Microservices for Helping Hands Application) and describes the steps to implement them using the Pedestal framework (Chapter 6, Introduction to Pedestal). In this chapter, you will learn how to:

• Implement Hexagonal design for microservices
• Create scalable microservices for Helping Hands using Pedestal
• Implement workflows for microservices using the Pedestal interceptor chain
• Implement the lookup service of Helping Hands to search for...

Implementing Hexagonal Architecture

Hexagonal Architecture (http://alistair.cockburn.us/Hexagonal+architecture), as shown in the following diagram, aims to decouple the business logic from the persistence and the service layer. Clojure provides the concept of a protocol (https://clojure.org/reference/protocols) that can be used to define the interfaces, that act as ports of Hexagonal Architecture. These ports can then be implemented by the adapters, resulting in a decoupled implementation that can be swapped based on the requirement. Execution of these adapters can then be triggered via Pedestal interceptors based on the business logic.

Designing the interceptor chain and context

The interceptor chain must be defined for each microservice of the Helping Hands application separately. Each interceptor chain may consist of interceptors that authenticate the request, validate the data models, and apply the business logic. Interceptors can also be added to interact with the Persistence layer and...

Creating a microservice for Service Consumer

The Service Consumer microservice exposes APIs for end users to register as a consumer of the Helping Hands application. To look up registered services and place an order, the user of the application must be registered as a Consumer. As per the workflow of Service Consumer defined in Chapter 3, Microservices for Helping Hands Application, it requires the following APIs to create new consumers, get consumer profiles, and update consumer details:

URI	Description
GET /consumers/:id/?flds=name,address	Gets the details of the consumer with the specified :id if the :id is specified, else it gets the details of the authenticated consumer. Optionally, it accepts a CSV of fields to be returned in the response.
PUT /consumers/:id	Creates a new consumer with the specified ID.
POST /consumers	Creates a new consumer and returns the ID.
DELETE /consumers/:id	Deletes the consumer with the specified ID.

Adding routes

Pedestal routes are added for each of the identified APIs...

Creating a microservice for Service Provider

The Service Provider microservice exposes APIs for end users to register as a service provider of the Helping Hands application. Service providers can register one or more services with the Helping Hands application that they are willing to fulfill if an order is placed against it. As per the workflow of Service Provider defined in Chapter 3, Microservices for Helping Hands Application, the following APIs are required to create new providers, get provider profiles, and update provider details:

Creating a microservice for Services

The Service microservice manages the list of services offered by the service providers via the Helping Hands application. It exposes APIs for service providers to register services that are offered by them. As per the workflow of Service, defined in Chapter 3, Microservices for Helping Hands Application, the following APIs are required to create a new service, get service details, and update service details. Each service must already have the service provider registered with the Helping Hands application via the Service Provider microservice. Since only an existing service provider can register a service, the service provider ID is retrieved by the Auth token received with the request calling the Service API to create a new service:

URI	Description
GET /providers/:id/?flds=name,mobile	Gets the details of the service provider with the specified :id if the :id is specified, else it gets the details of the authenticated user registered as a service provider. Optionally, it accepts a CSV of fields to be returned in the response.
PUT /providers/:id	Creates a new provider with the specified ID.
POST /providers	Creates a new provider and returns the ID.
PUT /providers/:id/rate	Adds to the latest ratings...

Creating a microservice for Order

The OrderService receives the request from Service Consumers to create a new order for the service provided by a particular service provider. It exposes the following APIs for consumers to create a new order, get order details, and get the list of orders placed by them. It also allows the consumers to rate the Order based on the quality of service received. To create a new Order, APIs expect a service ID and provider ID to be specified along with the required details such as time slot, and more. The consumer ID is picked from the Auth token that is received as a part of request headers. The IDs specified for Service and Service Provider must already be registered with the Helping Hands application via the Service and Service Provider microservices. Creation of an Order also makes sure that the requested service is offered within the vicinity of the consumer based on the geolocation of the consumer and service being requested:

URI	Description
GET /services/:id/?flds=name,mobile	Gets the details of the service with the specified :id if the :id is specified. Optionally, it accepts a CSV of fields to be returned in the response.
PUT /services/:id	Creates...

Creating a microservice for Lookup

The Lookup service is used to search for services by type, geolocation, and availability. It subscribes to the events generated by the Consumer, Provider, Service, and Order microservices as an Observer and keeps a denormalized dataset that is faster to query for required Services. The Lookup service also adds longitude and latitude for the Services and Consumers that is derived from their address and service area or locality. To get the longitude and latitude from the service area, it depends on an external API. The Lookup service provides the following APIs for consumers to search for a service and also filter the services by type, ratings, and providers:

URI	Description
GET /orders/?flds...

Creating a microservice for alerts

The Alert service is used to send email alerts and SMS. Alerts can be generated at various levels by other microservices. For example, successful creation of a consumer, provider, service, or an order may require an email to be sent to the relevant stakeholders. Similarly, alerts may be required whenever there is a change in the status of the order or a rating is received. The Alert service does not maintain a local database, it just generates events for each successful alert sent that can be tracked for monitoring purposes. The following table lists the endpoints for the Alert service:

URI	Description
GET /lookup/?q=query	Filters all the services based on the specified query.
GET /lookup/?q=query&type=type	Filters all the services of a given type based on the specified query.
GET /lookup/geo/?tl=40.73,-74.1&br=40.01,-71.12	Looks up the service by the given latitude-longitude set for...

URI	Params	Description
POST /alerts/email	to, cc, subject, body	Sends an alert via email to one or more recipients.
POST /alerts/sms	to, body	Sends an alert via SMS to one or more recipients.

Adding routes

Mostly, the Alert service will listen for events as an Observer and will not receive requests to send alerts via routes. If it is required to send alerts synchronously, the /alerts...

Summary

In this chapter, we focused on the step-by-step implementation of Helping Hands microservices using the Pedestal framework. We learned how to implement Hexagonal Architecture using Clojure protocols (https://clojure.org/reference/protocols) and Pedestal interceptors. We also implemented the required microservices for the Helping Hands application in Pedestal. In the next chapter, we will learn how to configure our microservices and maintain the runtime state of the application that includes connection with persistent storage and message queues to store data and send events, respectively.

The rest of the chapter is locked

Creating a microservice for Service Provider

The Service Provider microservice exposes APIs for end users to register as a service provider of the Helping Hands application. Service providers can register one or more services with the Helping Hands application that they are willing to fulfill if an order is placed against it. As per the workflow of Service Provider defined in Chapter 3, Microservices for Helping Hands Application, the following APIs are required to create new providers, get provider profiles, and update provider details:

Creating a microservice for Services

The Service microservice manages the list of services offered by the service providers via the Helping Hands application. It exposes APIs for service providers to register services that are offered by them. As per the workflow of Service, defined in Chapter 3, Microservices for Helping Hands Application, the following APIs are required to create a new service, get service details, and update service details. Each service must already have the service provider registered with the Helping Hands application via the Service Provider microservice. Since only an existing service provider can register a service, the service provider ID is retrieved by the Auth token received with the request calling the Service API to create a new service:

URI	Description
GET /providers/:id/?flds=name,mobile	Gets the details of the service provider with the specified :id if the :id is specified, else it gets the details of the authenticated user registered as a service provider. Optionally, it accepts a CSV of fields to be returned in the response.
PUT /providers/:id	Creates a new provider with the specified ID.
POST /providers	Creates a new provider and returns the ID.
PUT /providers/:id/rate	Adds to the latest ratings...

Creating a microservice for Order

The OrderService receives the request from Service Consumers to create a new order for the service provided by a particular service provider. It exposes the following APIs for consumers to create a new order, get order details, and get the list of orders placed by them. It also allows the consumers to rate the Order based on the quality of service received. To create a new Order, APIs expect a service ID and provider ID to be specified along with the required details such as time slot, and more. The consumer ID is picked from the Auth token that is received as a part of request headers. The IDs specified for Service and Service Provider must already be registered with the Helping Hands application via the Service and Service Provider microservices. Creation of an Order also makes sure that the requested service is offered within the vicinity of the consumer based on the geolocation of the consumer and service being requested:

URI	Description
GET /services/:id/?flds=name,mobile	Gets the details of the service with the specified :id if the :id is specified. Optionally, it accepts a CSV of fields to be returned in the response.
PUT /services/:id	Creates...

Creating a microservice for Lookup

The Lookup service is used to search for services by type, geolocation, and availability. It subscribes to the events generated by the Consumer, Provider, Service, and Order microservices as an Observer and keeps a denormalized dataset that is faster to query for required Services. The Lookup service also adds longitude and latitude for the Services and Consumers that is derived from their address and service area or locality. To get the longitude and latitude from the service area, it depends on an external API. The Lookup service provides the following APIs for consumers to search for a service and also filter the services by type, ratings, and providers:

URI	Description
GET /orders/?flds...

Creating a microservice for alerts

The Alert service is used to send email alerts and SMS. Alerts can be generated at various levels by other microservices. For example, successful creation of a consumer, provider, service, or an order may require an email to be sent to the relevant stakeholders. Similarly, alerts may be required whenever there is a change in the status of the order or a rating is received. The Alert service does not maintain a local database, it just generates events for each successful alert sent that can be tracked for monitoring purposes. The following table lists the endpoints for the Alert service:

URI	Description
GET /lookup/?q=query	Filters all the services based on the specified query.
GET /lookup/?q=query&type=type	Filters all the services of a given type based on the specified query.
GET /lookup/geo/?tl=40.73,-74.1&br=40.01,-71.12	Looks up the service by the given latitude-longitude set for...

URI	Params	Description
POST /alerts/email	to, cc, subject, body	Sends an alert via email to one or more recipients.
POST /alerts/sms	to, body	Sends an alert via SMS to one or more recipients.

Adding routes

Mostly, the Alert service will listen for events as an Observer and will not receive requests to send alerts via routes. If it is required to send alerts synchronously, the /alerts...

Summary

In this chapter, we focused on the step-by-step implementation of Helping Hands microservices using the Pedestal framework. We learned how to implement Hexagonal Architecture using Clojure protocols (https://clojure.org/reference/protocols) and Pedestal interceptors. We also implemented the required microservices for the Helping Hands application in Pedestal. In the next chapter, we will learn how to configure our microservices and maintain the runtime state of the application that includes connection with persistent storage and message queues to store data and send events, respectively.

The rest of the chapter is locked

Creating a microservice for Services

The Service microservice manages the list of services offered by the service providers via the Helping Hands application. It exposes APIs for service providers to register services that are offered by them. As per the workflow of Service, defined in Chapter 3, Microservices for Helping Hands Application, the following APIs are required to create a new service, get service details, and update service details. Each service must already have the service provider registered with the Helping Hands application via the Service Provider microservice. Since only an existing service provider can register a service, the service provider ID is retrieved by the Auth token received with the request calling the Service API to create a new service:

Creating a microservice for Order

The OrderService receives the request from Service Consumers to create a new order for the service provided by a particular service provider. It exposes the following APIs for consumers to create a new order, get order details, and get the list of orders placed by them. It also allows the consumers to rate the Order based on the quality of service received. To create a new Order, APIs expect a service ID and provider ID to be specified along with the required details such as time slot, and more. The consumer ID is picked from the Auth token that is received as a part of request headers. The IDs specified for Service and Service Provider must already be registered with the Helping Hands application via the Service and Service Provider microservices. Creation of an Order also makes sure that the requested service is offered within the vicinity of the consumer based on the geolocation of the consumer and service being requested:

Creating a microservice for Lookup

The Lookup service is used to search for services by type, geolocation, and availability. It subscribes to the events generated by the Consumer, Provider, Service, and Order microservices as an Observer and keeps a denormalized dataset that is faster to query for required Services. The Lookup service also adds longitude and latitude for the Services and Consumers that is derived from their address and service area or locality. To get the longitude and latitude from the service area, it depends on an external API. The Lookup service provides the following APIs for consumers to search for a service and also filter the services by type, ratings, and providers:

Creating a microservice for alerts

The Alert service is used to send email alerts and SMS. Alerts can be generated at various levels by other microservices. For example, successful creation of a consumer, provider, service, or an order may require an email to be sent to the relevant stakeholders. Similarly, alerts may be required whenever there is a change in the status of the order or a rating is received. The Alert service does not maintain a local database, it just generates events for each successful alert sent that can be tracked for monitoring purposes. The following table lists the endpoints for the Alert service:

Summary

In this chapter, we focused on the step-by-step implementation of Helping Hands microservices using the Pedestal framework. We learned how to implement Hexagonal Architecture using Clojure protocols (https://clojure.org/reference/protocols) and Pedestal interceptors. We also implemented the required microservices for the Helping Hands application in Pedestal. In the next chapter, we will learn how to configure our microservices and maintain the runtime state of the application that includes connection with persistent storage and message queues to store data and send events, respectively.