This repository contains the MicroProfile implementation of the Orders Service which is a part of the 'IBM Cloud Native Reference Architecture' suite, available at https://github.com/ibm-cloud-architecture/refarch-cloudnative-kubernetes
- Introduction
- How it works
- API Endpoints
- Implementation
- Features and App details
- Deploying the Bluecompute App
- Run Orders Service locally
- References
This project is built to demonstrate how to build Orders Microservices applications using Microprofile. This application provides basic operations of saving and querying orders from a relational database as part of the Orders function of BlueCompute.
- Based on MicroProfile.
- Persist order data to a MySQL database.
- Transmit stock to Inventory using RabbitMQ
- OAuth 2.0 protected APIs
- Deployment options for Minikube environment and ICP.
The Orders MicroService serves 'IBM Cloud Native Reference Architecture' suite, available at https://github.com/ibm-cloud-architecture/refarch-cloudnative-kubernetes. Though it is a part of a bigger application, the Orders service is itself an application that persists the data of orders to a MYSQL database.
The Orders MicroService REST APIs are protected by OpenID Connect. These APIs identifies and validates the caller using mp-jwt tokens.
GET /orders/rest/orders
- Returns all orders. The caller of this API must pass a valid OAuth token.
The OAuth token is a JWT with the customer ID of the caller encoded in the
user_nameclaim. A JSON object array is returned consisting of only orders created by the customer ID
GET /orders/rest/orders/{id}
- Return order by ID. The caller of this API must pass a valid OAuth token.
The OAuth token is a JWT with the customer ID of the caller encoded in the
user_nameclaim. If theidof the order is owned by the customer passed in theIBM-App-Userheader, it is returned as a JSON object in the response; otherwiseHTTP 401is returned.
POST /orders/rest/orders
- Create an order. The caller of this API must pass a valid OAuth token. The OAuth token is a JWT with the customer ID of the caller encoded in the user_name claim. The Order object must be passed as JSON object in the request body with the following format:
{
"itemId": <item id>,
"count": <number of items in order>,
}
On success, HTTP 201 is returned with the ID of the created order in the Location response header.
MicroProfile is an open platform that optimizes the Enterprise Java for microservices architecture. In this application, we use MicroProfile 1.3. This includes:
- MicroProfile 1.0 (JAX-RS 2.0, CDI 1.2, and JSON-P 1.0)
- MicroProfile 1.2 (MicroProfile 1.0,
MicroProfile Fault Tolerance 1.0,
MicroProfile Health Check 1.0,
MicroProfile JWT Authentication 1.0.) - MicroProfile 1.3 ( MicroProfile Open Tracing 1.0, MicroProfile Open API 1.0, MicroProfile Metrics 1.1, MicroProfile Config 1.2)
You can make use of this feature by including this dependency in Maven.
<dependency>
<groupId>org.eclipse.microprofile</groupId>
<artifactId>microprofile</artifactId>
<version>1.3</version>
<type>pom</type>
<scope>provided</scope>
</dependency>
You should also include a feature in server.xml.
<server description="Sample Liberty server">
<featureManager>
<feature>microprofile-1.3</feature>
</featureManager>
<httpEndpoint httpPort="${default.http.port}" httpsPort="${default.https.port}"
id="defaultHttpEndpoint" host="*" />
</server>
-
Java SE 8 - Used Java Programming language
-
CDI 1.2 - Used CDI for typesafe dependency injection
-
JAX-RS 2.0.1 - JAX-RS is used for providing both standard client and server APIs for RESTful communication by the MicroProfile applications.
-
Eclipse MicroProfile Config - Configuration data comes from different sources like system properties, system environment variables, *.properties etc. These values may change dynamically. This feature enables us to pick up configured values immediately after they got changed.
The config values are sorted according to their ordinal. We can override the less important values from outside. The config sources three locations by default, and the list below shows their rank in priority from most to least:
- System.getProperties()
- System.getenv()
- all META-INF/microprofile-config.properties files on the ClassPath.
In our sample application, we obtained the configuration programmatically.
-
MicroProfile JWT Authentication - MicroProfile JWT Authentication for token based authentication. It uses OpenIDConnect based JSON Web Tokens (JWT) for role based access control to our REST endpoints. This allows the system to verify, authorize and authenticate the user based the security token given.
-
MicroProfile Health Check - For MicroProfile implementations, this feature helps us determine the status of the service as well as its availability. This helps us to identify if the service is healthy or not. If the service is down, we can investigate the reasons behind its termination or shutdown.
In our sample application, we injected this
/healthendpoint in our liveness probes. -
MicroProfile OpenAPI - This feature helps us to expose the API documentation for the RESTful services. It allows the developers to produce OpenAPI v3 documents for their JAX-RS applications.
In our sample application we used @OpenAPIDefinition, @Info, @Contact, @License, @APIResponses, @APIResponse, @Content, @Schema, @Operation and @Parameter annotations.
-
MicroProfile OpenTracing - Enables and allows for custom tracing of JAX-RS and non-JAX-RS methods. It helps us to analyze the transaction flow so that the we can easily debug the problematic services and fix them.
In our sample application, we used Zipkin as our distributed tracing system. We used @Traced and an ActiveSpan object to retrieve messages.
-
MicroProfile Metrics - Used to help monitor essential system parameters and the performance of well-known endpoints.
In our sample application, we use @Timed, @Counted, @Metered.
To build and run the entire BlueCompute demo application, each MicroService must be spun up together. This is due to how we set up our Helm charts structure and how we dynamically produce our endpoints and URLs.
Further instructions are provided here.
To deploy it on IBM Cloud Private, please follow the instructions provided here.
To deploy it on Minikube, please follow the instructions provided here.
To deploy the Orders app locally using Maven or Helm and test the individual service, please follow the instructions provided here.