REST API - Micronaut MongoDB

Gemini Docs
Search…
v0.6.0-SNAPSHOT
Gemini Overview
Backend Module
REST API - Micronaut MongoDB
Rest API
The Schema (DDD)
Data Drivers
REST API - Micronaut MongoDB
This is a Micronaut starter project that use the basic features of Gemini and store data by using the MongoDb driver. To start you just need Docker and a MongoDB database (you can use the free MongoDB Atlas cloud database)
In the repository page there is a full tutorial where in a matter of minutes you can see:
how to define a simple Gemini Schema to describe your data
how to run a Gemini REST API service using Docker and MongoDB
how to start interacting with basic CRUD REST API over your data model
how to use advanced APIs like counts, search and filters
how to order data results and use pagination
how to configure REST APIs
Let's see some of the main tutorial concepts here....
Step 1 - Define the Schema
Schema is your data model, it is a YAML file that Gemini uses to generate all the API controllers and to map data.
1
type: ENTITY
2
entity:
3
  name: CATEGORY
4
  lk: [id]
5
  fields:
6
    - name: id
7
      type: STRING
8
      required: true
9
    - name: description
10
      type: STRING
11
​
12
---
13
​
14
type: ENTITY
15
entity:
16
  name: PRODUCT
17
  lk: [id]
18
  fields:
19
    - name: id
20
      type: STRING
21
      required: true
22
    - name: name
23
      type: STRING
24
    - name: description
25
      type: STRING
26
    - name: available
27
      type: BOOL
28
    - name: status
29
      type: ENUM
30
      enums: [DRAFT, PENDING, PRIVATE, PUBLISH]
31
    - name: regular_price
32
      type: DOUBLE
33
    - name: sale_price
34
      type: DOUBLE
35
    - name: categories
36
      type: ARRAY
37
      array:
38
        type: ENTITY_REF
39
        entityRef:
40
          entity: CATEGORY
Copied!
Step 2 - Run the Docker Image
After defining the data schema, we can start Gemini, exposing all the REST APIs. You can see further documentation for the env variables in the repo tutorial.
1
docker run -p 8080:8080 \
2
-e GEMINI_SCHEMAS=/schemas/product_schema.yaml \
3
-e GEMINI_MONGODB_URL="mongodb+srv://_mongo_user:[email protected]__path__.mongodb.net/db?retryWrites=true&w=majority" \
4
-e GEMINI_MONGODB_DB=starter \
5
-v $(pwd)/product_schema.yaml:/schemas/product_schema.yaml:ro \
6
aat7/gemini-micronaut-mongodb-restapi
Copied!
This is the easiest way to start Gemini. Please note that in the previous Docker command we simply specify a Gemini Schema, and the Data Driver (MongoDB) parameters.
Below (and better in the repo tutorial) it is also possibile to provide a REST API configuration, for example to handle big data entities.
Step 3 - Use the REST APIs
Common APIS are CRUD REST APIs to insert, modify, delete and get data.
The url pattern for a particular entity is  <base_url>/data/{entityName}
Here is a list of some curl CRUD calls, but take a look at the repo tutorial to see also responses and further details.
1
# POST data to add a category
2
curl --request POST "http://localhost:8080/data/category" \
3
--header "Content-Type: application/json" \
4
-d '{"data": {"id": "tech-1",
5
        "description": "Technology"
6
    }
7
  }'
8
  
9
# GET ALL data for an entity
10
curl "http://localhost:8080/data/category"
11
​
12
# GET ID 
13
curl "http://localhost:8080/data/category/smartphone-1"
14
​
Copied!
Step 4 - Count and Filter APIs
Gemini supports also other APIs like the count, and special filters (based on field types). Take a look at the repo tutorial to see also responses and further details.
To count record simply use a GET with the url pattern /entity/{entityName}/recordCounts. 
1
curl "http://localhost:8080/entity/product/recordCounts"
Copied!
Filters instead can be specified with common query string parameters. They works both with data APIs and recordCounts API.
Some examples to filter out and count specific products (remember to a look at the repo tutorial to have more details and explanations):
1
# Count - Iphone 13 128 GB Blue - NB: the space is %20 in curl url
2
curl "http://localhost:8080/entity/product/recordCounts?name=Iphone%2013%20128%20GB%20Blue"
3
{"status":"success","data":{"count":1},"meta":{"elapsedTime":"38ms"}}
4
​
5
# Get Record - Iphone 13 128 GB Blue
6
curl "http://localhost:8080/data/product?name=Iphone%2013%20128%20GB%20Blue"
7
{"status":"success","data":[{"regular_price":799.0,"name":"Iphone 13 128 GB Blue","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Blue","id":"iphone-13-128-blue","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"}],"meta":{"elapsedTime":"49ms"}}
8
​
9
# Count products with price GT (Greather Than >) 700
10
curl "http://localhost:8080/entity/product/recordCounts?regular_price[GT]=700"
11
{"status":"success","data":{"count":10},"meta":{"elapsedTime":"40ms"}}
12
​
13
# 10 products with price >= 799 
14
curl "http://localhost:8080/entity/product/recordCounts?regular_price[GTE]=799"
15
{"status":"success","data":{"count":10},"meta":{"elapsedTime":"39ms"}}
16
​
Copied!
Step 5 - Pagination & Big Entities
Gemini provide pagination out of the box for all the entities. Just use the start and the limit query string parameters to provide page size a navigate among pages and records. You can decide the pagesize by yourself with limit and go to the next page with start.
1
# First page of 2 elements for the category Entity
2
curl "http://localhost:8080/data/category/?start=0&limit=2"
3
​
4
# Continue with the page number 2
5
curl "http://localhost:8080/data/category/?start=2&limit=2"
Copied!
Usually you don't want to allow the GET ALL data API for very big entities (with thousands or millions records). In this situation you want the pagination to work as default behaviour.
You can achieve this goal providing a REST configuration and specifying the default limit. In the repository documentation you can find an example YAML file (restconfig.yaml) available for you.
1
# restconfig.yaml 
2
​
3
type: ENTITY
4
entity: PRODUCT
5
config:
6
  getListStrategy: START_LIMIT
7
  defaultLimit: 5
Copied!
Now let's use the new file restconfig.yaml to provide the rest configuration for the Product entity. Always take a look here to know more about docker parameters.
1
docker run -p 8080:8080 \
2
        -e GEMINI_SCHEMAS=/schemas/product_schema.yaml \
3
        -e GEMINI_REST_CONFIGS=/rest/restconfig.yaml \
4
        -e GEMINI_MONGODB_URL="mongodb+srv://root:[email protected]/db?retryWrites\=true&w\=majority" \
5
        -e GEMINI_MONGODB_DB=testdb_1 \
6
        -v $(pwd)/product_schema.yaml:/schemas/product_schema.yaml:ro \
7
        -v $(pwd)/restconfig.yaml:/rest/restconfig.yaml:ro \
8
        aat7/gemini-micronaut-mongodb-restapi

Copied!
The service is running so let's make a simple call to count the products. As you can see from the curl command, the count API returns 560 records.
1
curl "http://localhost:8080/entity/product/recordCounts"
2
{"status":"success","data":{"count":560},"meta":{"elapsedTime":"57ms"}}
Copied!
Now let's make a GET call to the the Products root. We don't add the limit parameter but the framework automatically assign to the API the limit=5. Just take a look at the result, and the limit field inside the meta response body object (at the end of the JSON response).
1
curl "http://localhost:8080/data/product/"
2
{"status":"success","data":[{"regular_price":799.0,"name":"Iphone 13 128 GB Blue","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Blue","id":"iphone-13-128-blue","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"},{"regular_price":799.0,"name":"Iphone 13 128 GB Starlight","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Starlight","id":"iphone-13-128-starlight","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"},{"regular_price":799.0,"name":"Iphone 13 128 GB Midnight","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Midnight","id":"iphone-13-128-midnight","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"},{"regular_price":799.0,"name":"Iphone 13 128 GB Pink","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Pink","id":"iphone-13-128-pink","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"},{"regular_price":799.0,"name":"Iphone 13 128 GB Red","available":true,"description":"Apple Iphone 13 - Memory: 128 GB - Color: Product RED","id":"iphone-13-128-red","categories":["tech-1","smartphone-1"],"sale_price":699.0,"status":"PUBLISH"}],"meta":{"limit":5,"start":0,"elapsedTime":"43ms"}}
Copied!
Next Steps
Now that you are able to use all the basic features of Gemini you can start to model your own use case, so your own entities and data schema. If the mongo driver is enough for you just use the docker starter, otherwise you could develop your own data driver.
Backend Module - Previous
Getting Started
Next - Backend Module
Rest API
Last modified 3mo ago
Copy link
Contents
Step 1 - Define the Schema
Step 2 - Run the Docker Image
Step 3 - Use the REST APIs
Step 4 - Count and Filter APIs
Step 5 - Pagination & Big Entities
Next Steps