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.
type: ENTITY
entity:
name: CATEGORY
lk: [id]
fields:
- name: id
type: STRING
required: true
- name: description
type: STRING
---
type: ENTITY
entity:
name: PRODUCT
lk: [id]
fields:
- name: id
type: STRING
required: true
- name: name
type: STRING
- name: description
type: STRING
- name: available
type: BOOL
- name: status
type: ENUM
enums: [DRAFT, PENDING, PRIVATE, PUBLISH]
- name: regular_price
type: DOUBLE
- name: sale_price
type: DOUBLE
- name: categories
type: ARRAY
array:
type: ENTITY_REF
entityRef:
entity: CATEGORYStep 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.
docker run -p 8080:8080 \
-e GEMINI_SCHEMAS=/schemas/product_schema.yaml \
-e GEMINI_MONGODB_URL="mongodb+srv://_mongo_user:_mongo_pwd_@__path__.mongodb.net/db?retryWrites=true&w=majority" \
-e GEMINI_MONGODB_DB=starter \
-v $(pwd)/product_schema.yaml:/schemas/product_schema.yaml:ro \
aat7/gemini-micronaut-mongodb-restapiStep 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.
# POST data to add a category
curl --request POST "http://localhost:8080/data/category" \
--header "Content-Type: application/json" \
-d '{"data": {"id": "tech-1",
"description": "Technology"
}
}'
# GET ALL data for an entity
curl "http://localhost:8080/data/category"
# GET ID
curl "http://localhost:8080/data/category/smartphone-1"
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.
curl "http://localhost:8080/entity/product/recordCounts"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):
# Count - Iphone 13 128 GB Blue - NB: the space is %20 in curl url
curl "http://localhost:8080/entity/product/recordCounts?name=Iphone%2013%20128%20GB%20Blue"
{"status":"success","data":{"count":1},"meta":{"elapsedTime":"38ms"}}
# Get Record - Iphone 13 128 GB Blue
curl "http://localhost:8080/data/product?name=Iphone%2013%20128%20GB%20Blue"
{"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"}}
# Count products with price GT (Greather Than >) 700
curl "http://localhost:8080/entity/product/recordCounts?regular_price[GT]=700"
{"status":"success","data":{"count":10},"meta":{"elapsedTime":"40ms"}}
# 10 products with price >= 799
curl "http://localhost:8080/entity/product/recordCounts?regular_price[GTE]=799"
{"status":"success","data":{"count":10},"meta":{"elapsedTime":"39ms"}}
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.
# First page of 2 elements for the category Entity
curl "http://localhost:8080/data/category/?start=0&limit=2"
# Continue with the page number 2
curl "http://localhost:8080/data/category/?start=2&limit=2"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.
# restconfig.yaml
type: ENTITY
entity: PRODUCT
config:
getListStrategy: START_LIMIT
defaultLimit: 5Now 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.
docker run -p 8080:8080 \
-e GEMINI_SCHEMAS=/schemas/product_schema.yaml \
-e GEMINI_REST_CONFIGS=/rest/restconfig.yaml \
-e GEMINI_MONGODB_URL="mongodb+srv://root:[email protected]/db?retryWrites\=true&w\=majority" \
-e GEMINI_MONGODB_DB=testdb_1 \
-v $(pwd)/product_schema.yaml:/schemas/product_schema.yaml:ro \
-v $(pwd)/restconfig.yaml:/rest/restconfig.yaml:ro \
aat7/gemini-micronaut-mongodb-restapi
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.
curl "http://localhost:8080/entity/product/recordCounts"
{"status":"success","data":{"count":560},"meta":{"elapsedTime":"57ms"}}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).
curl "http://localhost:8080/data/product/"
{"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"}}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.
Last updated