Getting Started

Light-4j frameworks provide middleware handlers to address cross-cutting concerns for your application so that you only need to implement the final business handlers to process the request and return a response without thinking about exception handling, metrics, traceability, correlation, security, validation, etc. If you have the specification available, the light-codegen can scaffold the application for you to fill in the business logic into the generated handlers and write assertions in the generated tests for these handlers.

Local Development Environment

If you don’t have JDK 11 and Git installed, please prepare your environment.

Choose a framework

There are several frameworks available to support different styles of API. If this is the very first time you try to create an API, please try light-rest-4j. If you are unsure which style you should choose for your project, please visit API category.

Light-4j - For an expert that needs absolute high throughput and low latency
Light-rest-4j - Restful API with OpenAPI 3.0 or Swagger 2.0 specification
Light-graphql-4j - GraphQL API with query, mutation and subscription based on IDL
Light-hybrid-4j - RPC style of hybrid monolithic and microservices serverless framework
Light-tram-4j - Guaranteed transactional message/commmand/event delivery between services
Light-eventuate-4j - An eventual consistency framework based on Event Sourcing and CQRS
Light-saga-4j - A saga implementation to manage distributed transaction across multiple microservices
Light-spring-boot - Leverage light-4j middleware handlers in existing Spring Boot application
Web Server - A web server that serves static content and APIs
WebSocket - A WebSocket server to support client to client or client to server communication
Light-session-4j - Distributed session managers (Redis, Hazelcast, JDBC) that support server cluster
Light-spa-4j - A set of middleware handlers for Single Page Application

Set up an infrastructure service

Services we built

Light-oauth2 - OAuth 2.0 provider implemented as microservices for microservices
Light-portal - A portal UI that integrate all the services to manage the life-cycle of services
Light-router - Working with external client or client not implemented in Java 8 and above
Light-proxy - Deploys in front of legacy API application to address cross-cutting concerns
Light-config-server - Centralized configuration and secret management service
Light-tokenization - Tokenizes sensitive info before sending info outside of corporate network

Services we integrated

Consul - For service registration and discovery
Kafka - Message broker that is most popular with event based frameworks
Elasticsearch - Centralized logging index and analysis
InfluxDB - Pushes the metrics data to the time series database
Prometheus - Pulls the metrics data from each individual service
Kubernetes - Vanilla Kubernetes cluster platform
Openshift - Commercial Kubernetes cluster platform

Leverage a tool

Tools we built

Light-bot - A microservice based DevOps agent that handles multiple repositories and dependencies
Light-codegen - A code generator based on the rocker that can be used as a utility or web service
Swagger-bundler - A utility merges multiple Swagger spec files into a file with external references resolved
Openapi-bundler - A utility merges multiple OpenAPI spec files into a file with external references resolved

Tools we used

Wrk - Performance test tool that can generate enough requests per second

Consume API or service

Service Consumer - Client to service or service to service communication

Getting Started

The easiest way to start your RESTful API project is by starting with the Swagger 2.0 specification or OpenAPI 3.0 specification. Here is a video to show you how to generate a project from Swagger spec.

light-4j-getting-started

And here is the step by step REST tutorial one walking through Swagger petstore example and the other is a OpenAPI petstore example.

If you are interested in GraphQL framework, please refer to light-graphql-4j.

We also have a RPC/Hybrid framework that support JSON RPC and you can find some info at light-hybrid-4j.

For event-driven service, you might be interested in light-eventuate-4j.

Examples

Another way to start a new project is to copy from an existing example and expand on it. This is not recommended but if you don’t have IDL(Interface Definition Language) specification like OpenAPI specification or your service has a very special requirement that cannot be generated, you can find many example projects at a separate repo light-example-4j and start by copying one of them.

There are folders in light-example-4j that contains examples like:

rest folder contains examples built on top of light-rest-4j framework
graphql folder contains examples built on top of light-graphql-4j framework
hybrid folder contains examples built on top of light-hybrid-4j framework
eventuate folder contains examples built on top of light-eventuate framework

To get started, check out the Quick Start page, to gain a general knowledge of how our Light-4j platform can be used and built upon.

Tutorials

Follow the microservices tutorial to build multiple services that communicate each other. The source code for the tutorial can be found at [https://github.com/networknt/light-example-4j]

api_a is calling api_b and api_c
api_b is calling api_d
api_c is an independent service
api_d is an independent service

Environment

JDK 8 or JDK 11 (Mandatory) Currently, the majority of the components in Light 1.5.x or 1.6.x is based on Java 8, and master 2.0.x is based on Java 11. Before starting your first project, we need to install the following software packages on your system. Most of our customers are working on light-4j production ready 1.5.x and 1.6.x versions which are dependent on Java 8. We have released 2. Read More »

Light Codegen Tool

The code generator light-codegen could be used to support project scaffolding for all the frameworks provided by Light. The code generator based on Rocker template engine that can be used as a utility or web service. It is used currently as scaffold services which include light-rest-4j, light-graphql-4j, light-eventuate-4j and light-hybrid-4j. Workflow Light-codegen generates initialized microservice projects based on user-defined specification and configuration file: – Light-rest-4j for OpenAPI based generation: OpenAPI JSON/YAML format specification and configuration file Read More »

Light Tram 4j

light-tram-4j is a port from eventuate-tram-core built by Chris Richardson. The client API is the same but implemented not in Spring framework but light-4j instead. There are three frameworks in light-platform focused on event driven microservices and light-tram-4j is the most fundamental one. Tram stands for transactional messaging. Ir enables an application to automatically update state and send a message or a domain event as part of a database transaction. Tram is a framework of ensuring data consistency within a microservices architecture. Read More »

Light Rest 4j

The light-rest-4j is a framework that is designed to speed up RESTful API development and deployment. On top of light-4j, it has several middleware handlers specifically designed around Swagger 2.0 and OpenAPI 3.0 specifications. With the specification ready, you can scaffold project with light-codegen, and the specification will be loaded during the runtime to enable JWT scope verification and schema validation for the request based on the spec. Setup Local Development Environment Build Systems and Dependency Management Design First Create an OpenAPI 3. Read More »

Light Graphql 4j

GraphQL is a new style of protocol open sourced by Facebook and it is getting popular especially in Mobile and Single Page Applications as a front end. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. light-graphql-4j is a GraphQL framework built on top of light-4j and graphql-java. Read More »

Light Hybrid 4j

For public APIs, it makes sense to use RESTful; however, if it is an internal API, the RPC based API style will be more efficient. These days, Javascript on the browser is really powerful, and it can deal with JSON or other binary protocols very easily. These browser objects (JSON/Binary) contain type information so that there is no need to do Object to URI and URI to Object transformation based on OpenAPI specification or RAML. Read More »

Light Eventuate 4j

One of the major issues that we have seen occur in a system with microservices is the way transactions work when they span over different services. Within our old monolithic architecture, we have been using distributed transactions to resolve this, but they come with their own issues. It is very hard to avoid deadlocks and scale the application when business grows. Distributed transaction management is a key architectural consideration that needs to be addressed whenever you are proposing a microservices deployment model to a customer. Read More »

Light Oauth2

The nature of the services is easy to access so security is the most important thing when deploying services. Light is a security first design and an OAuth 2.0 service provider is available as part of the ecosystem. Along with light-portal client registration and service registration, light-oauth2 provides more than normal OAuth 2.0 for microservices such as public key distribution, scope management, and distributed policy management. If you are new to OAuth 2. Read More »

Light Portal Service

Light encourages microservices or serverless architecture although it can be used to build monolithic services. When you have too many services running within the organization, managing these service specifications during development and instances during runtime can become a daunting job. Light-portal provides features that help you manage the entire life-cycle of services from planning to decommission. lightapi.net portal Install light-portal light-portal components Read More »

Light Router Server

While we have provided a client module in light-4j for the service consumer to interact with the service provider, there are certain scenarios in which it cannot be utilized. For example, the consumer is a PEGA workflow application that cannot easily include client.jar or the consumer is a service that is implemented with DotNet which cannot leverage the client.jar We are in the process of providing client modules for other languages and even providing frameworks for other languages; however, it takes time for these solutions to be production ready. Read More »

Light Proxy Server

For an organization that establishes infrastructure to support services built on top of Light, chances are they have some existing services built with other platforms or even different languages. To leverage the security, metrics, logging, tracing, auditing, client-side service discovery for these existing services, it is a good idea to put light-proxy in front of these services to provide cross-cutting concerns and gateway features for them. Although the light-proxy adds an additional network hop, however, it might be faster given it supports HTTP 2. Read More »

Light Config Server

Each plugin in Light has a configuration file to control if the component is enabled and its behaviour during runtime. Most modules have a default configuration file in the module src/main/resources/config folder that can be overridden by the application level configuration with the same file name in the same location. Also, the configuration files can be externalized to a file system folder specified by a system property. To help manage these config files in a hierarchical structure, we have created a config server for services to load their config during startup. Read More »

Light Saga 4j

In microservices architecture, one request might trigger multiple services in the call stack, so to ensure data consistency between services, we have provided light-saga-4j to manage distributed transactions. Sagas require your services to be idempotent and provide a compensation action for each update action. light-saga-4j is built on top of light-eventuate-4j. Read More »

Light Session 4j

Most people think Light is only for services as it is our forte. However, it can be used to build web applications that support Mobile Native and Single Page applications. To provide Single Sign-On and High availability, we need to support multiple instances of server running and session replication among them. Light-session-4j is designed for this and it supports in-memory, Hazelcast, Redis and JDBC for session replication. Read More »

Webserver

Most people use Light to build services instead of web servers; however, today’s Mobile Native applications and Single Page applications running on browsers makes the traditional server side rendering provided by Java EE obsolete. For your browsers and mobile devices you need a web server that can serve Javascript with static content as well as APIs. This is the strength of Light. Read More »

Websocket

HTTP protocol is pretty efficient, especially HTTP 2.0; however, to handle repeated communication between server to browser or between browser to browser, nothing can compete with Websocket. Once the connection is established, the communication channel is open until it is closed. It is very efficient to handle messages or events in an event driven application. Read More »

Start rest service by example

Another way to start a brand new project is to copy from one of the existing examples. You can find several Restful API examples at light-example-4j repository and the majority of them has a tutorial to walk you through step by step. If you are interested in implementing your service in Kotlin, you can find examples in light-example-kotlin repository. Read More »

Start a service from light-codegen

The light-4j framework is a design-driven framework which means you have to start with the specification before starting with code. It makes sense as the contract is the most important thing for a service and it should be finalized before coding is started. The easy way to start a microservice with the light-rest-4j framework is to use light-codegen to scaffold a running application based on your Swagger 2.0 specification or OpenAPI 3. Read More »

First Application

To be completed. Read More »

Build Systems and Dependency Management

It is strongly recommended that you choose a build system that supports dependency management and that can consume artifacts published to the “Maven Central” repository. We would recommend that you choose Maven or Gradle. It is possible to get Light-4j to work with other build systems (Ant, for example), but they are not well supported. Dependency Management Each release of Light-4j provides a list of dependencies that it supports. In practice, you do not need to provide a version for any of these dependencies in your build configuration but only light-4j version. Read More »