api

README

       

Overview

Kicksware API provides both RESTful and gRPC interfaces to grand access, control, and management of the Kicksware sneaker resale platform while it's designed as a microservice-based, cloud-native, composite solution that collectively represents a set of a lightweight, stateless web-services, each written in Golang.

Table of contents

• Overview
• Table of contents
• Endpoints
  • REST
  • gRPC
• Authentication
• Architecture
• Internal design
• Requirements
• Deployment
• Wrap Up
• License

Endpoints

REST

All API's endpoints are divided into 10 base resources which mostly correspond to their source microservices as follows:

Service	Server URL	Endpoint base resources
users-service	api.kicksware.com	/users, /auth, /mail, /interact
references-service	api.kicksware.com	/references/sneakers
products-service	api.kicksware.com	/products/sneakers
search-service	api.kicksware.com	/search
orders-service	api.kicksware.com	/orders
cdn-service	cdn.kicksware.com	/
*	*.kicksware.com	/health

RESTful API uses api.kicksware.com subdomain as it's base server URL.

An exception is the Content Deliver Network (CDN) service, which as it's own subdomain cdn.kicksware.com.

API is accessible from both :443 port via HTTPS and :80 via plain HTTP.

The full API specification is available on Swagger and Readme.io.

gRPC

As it is cloud-native and microservice-based application, Kicksware also provides RPC API using gRPC framework and Protocol Buffers language.

Like many RPC systems, gRPC is based on the concept of defining a service in terms of functions (methods) that can be called remotely. This approach is especially useful for distributed, loose-coupled systems, as it provides a mechanism to write API specification ones as a set of .proto files from witch API implementation can be generated on any language.

All .proto specification files are available here.

gRPC API logical division is also based on source microservice entries as follows:

Service	Server URL	Proto endpoints
users-service	rpc.kicksware.com	/proto.UserService, /proto.AuthService, /proto.MailService, /proto.InteractService
references-service	rpc.kicksware.com	/proto.ReferenceService
products-service	rpc.kicksware.com	/proto.ProductService
search-service	rpc.kicksware.com	/proto.SearchReferenceService, /proto.SearchProductService
orders-service	rpc.kicksware.com	/proto.OrdersService
cdn-service	cdn.kicksware.com	/proto.CDNService

Authentication

JSON Web Token (JWT) is used to authenticate and authorize all REST requests.

To access gRPC based API, both secure TLS connection and token interceptors are required.

Architecture

As it was mentioned earlier Kicksware API design is based completely on microservice architecture pattern.

Like any other, this approach has its own pros and cons. The common right way to decide whether a specific architecture is suits a specific system or not, is by using what's calls architecture trade-off analysis method (ATAM). Basically, this method compares software architectures relative to quality attribute goals and helps expose architectural risks that potentially inhibit the achievement of an organization’s business goals.

When evaluating a microservice architecture style, it is important to understand that this approach is generally harder to implement, maintain, and test and requires more staff, money, and resources, but as a trade-off microservices provides one the most effective method of Horizontal scaling. And as a bonus you'll get higher flexibility as each new web-service can be written in any language and using any technology as long as it has some kind of communication mechanism (API).

As for this particular project the main goal was to reverse engineer evaluating process and build the system that would fit MSA the best way possible.

Internal design

While microservice architecture divides the entire system into small, independent services, it's important for a code to stay organized and clean even in scale of one microservice.

For this purpose Kicksware design adopts uncle Bob's Clean Architecture - another grate architecture pattern that separates the design elements into ring levels and its basic rule is that code dependencies can only come from the outer levels inward, so the further in you go, the higher level the software becomes. Simply put, the code on the inner layers can have no knowledge of the code on the outer layers.

You may have seen diagrams like the following, but this one, in particular, is Kicksware custom API microservice Clean Architecture representational chart:

Requirements

API microservice registry should be deployed after Gateway and Tool Stack projects. The reason for this is DB and Elasticsearch dependencies from Tool Stack project and Traefik Proxy from Gateway project to route outer traffic to services.

Deployment

Kicksware project can be deployed using the following methods:

1. Docker Compose file

   This method requires single dedicated server with both installed docker and docker-compose utilities.

   Compose configuration file can be found in the root of the project. This file already contains setting for reverse proxy routing and load balancing.

   Gitlab CI deployment pipeline configuration file for compose method can be found in .gitlab directory.

2. Kubernetes Helm charts

   Deployment to Kubernetes cluster is the default and desired way.

   For more flexible and easier deployment Helm package manager is used. It provides a simple, yet elegant way to write pre-configured, reusable Kubernetes resource configuration using YAML and Go Templates (or Lua scripts). Helm packages are called charts.

   Each microservice has it's own chart in the root of it's directory:

   Service	Helm chart
   users-service	~/user-service/users-chart
   references-service	~/reference-service/references-chart
   products-service	~/product-service/products-chart
   search-service	~/search-service/search-chart
   orders-service	~/order-service/orders-chart
   cdn-service	~/cdn-service/cdn-chart

   Helm chart configuration already contains configuration of Traefik IngressRoute Custom Resource Definition (CRD) for reverse proxy routing and load balancing.

   Gitlab CI deployment pipeline configuration file for K8s method can be found in the root of the project.

Wrap Up

Kicksware API is the accumulation of Kicksware's business logic in the form of distributed, atomically granulated, stateless web-services, where each is responsible only for its entities, use cases, API endpoints.

It exposes access to the data and its functionality as a set of both RESTfull endpoints and gRPC remote procedures.

There are two ways to perform Kicksware API deployment. To ensure top performance with longer uptime and lesser latency while having effective and automated control over scalability, Kicksware utilizes Kubernetes cluster with minimum of 3 basic spec nodes and 2 more for potential cluster autoscaling.

An alternative and in fact, a cheaper and easier way to achieve sufficient results is for deployment to be performed with just one VPS server and docker-compose utility. However, such temporary savings now may be offset by the costs of vertical scaling when demand rises in the future.

More

See other Kicksware project repositories.

License

Licensed under the GNU AGPL-3.0.