{"id":15804916,"url":"https://github.com/ddobrin/todos-api","last_synced_at":"2025-03-31T22:02:12.499Z","repository":{"id":134175922,"uuid":"321808522","full_name":"ddobrin/todos-api","owner":"ddobrin","description":"A Spring Boot Microservice that uses spring-boot-starter-web to implement a REST API for TODO(s)","archived":false,"fork":false,"pushed_at":"2021-04-05T18:14:14.000Z","size":277,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-06T02:02:24.891Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddobrin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-15T22:51:51.000Z","updated_at":"2021-09-03T15:40:38.000Z","dependencies_parsed_at":"2023-03-13T11:07:10.396Z","dependency_job_id":null,"html_url":"https://github.com/ddobrin/todos-api","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddobrin%2Ftodos-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddobrin%2Ftodos-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddobrin%2Ftodos-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddobrin%2Ftodos-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddobrin","download_url":"https://codeload.github.com/ddobrin/todos-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246547387,"owners_count":20794970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-05T02:02:07.360Z","updated_at":"2025-03-31T22:02:12.477Z","avatar_url":"https://github.com/ddobrin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\nTODOS-API is a sample Spring Boot Microservice that uses spring-boot-starter-web to implement a REST API for TODO(s).\n\nThe service fits into a larger TODO application, which includes a WebUI, an edge service, as well as caching and database services.\n\n![alt text](https://github.com/tanzu-platform-architecture-canada/todos-api/blob/master/images/rest-api.png \"TODO Application\")\n\nThe service can be accessed from a Web UI or directly at the endpoints it exposes.\n\n## The Domain Model\nThe Domain Model is a TODO object which has an id, a title, a category, the deadline and the status.\n```json\nex.:\n{\n    \"category\": \"personal\",\n    \"complete\": false,\n    \"deadline\": \"2020/10/01\",\n    \"id\": \"4d0918be-36fa-4dcd-b7b8-14200ef31d4c\",\n    \"title\": \"todo3\"\n}\n```\n## Endpoints\n\n`todos-api` exposes multiple endpoints, by default running at port `8082`:\n\n* `/` - [GET] returns all TODO items \n* `/{id}` - [GET] returns a TODO items for the specified id\n* `/` - [POST] creates a new TODO item\n* `/{id}` - [POST] creates a new TODO item with a specified id, in lieu of an auto-generated id\n* `/{id}` - [PATCH] updates an existing TODO item \n* `/` - [DELETE] - deletes all TODOs in the database and evicts the cache\n* `/{id}` - [DELETE] - deletes a TODO for the specified id\n\n`todos-api` exposes additionally a separate set of endpoints for introspection, out-of-the-box and customized\n\n* `/actuator` - [GET] returns all actuators enabled in the application; by default almost all available actuators have been enabled, for educational purposes\n* `/actuator/health` - [GET] returns the OOB health info + customized health info collected from the service\n* `/actuator/custom` - [GET] implements a custom actuator\n* `/actuator/info` - [GET] collects customized info from the application\n\n## Pre-requisites for using TODOS-API\nBuilding and running the application assumes that you have installed a number of pre-requisites:\n\n* Java 11 - configured to run the application by default. You can decided to run also with Java 16 \n* Maven - compiling the application and running tests\n* Helm v3 - for installing the caching and database solutions. [Helm installation link](https://helm.sh/docs/intro/install/).\n* Skaffold - for building, pushing, deploying and debugging the application. [Skaffold installation link](https://skaffold.dev/docs/install/).\n* Kustomize - for using a template-free way to customize application configuration that simplifies the use of off-the-shelf applications. [Kustomize installation link](https://kubernetes-sigs.github.io/kustomize/installation/).\n* HTTPie - highly recommended as a cUrl replacement for a user-friendly command-line HTTP client for the API era. It comes with JSON support, syntax highlighting, persistent sessions, wget-like downloads, plugins, etc. [HTTPie installation link](https://httpie.org/).\n* Kubectl - the Kubernetes CLI, allows you to run commands against Kubernetes clusters. [Kubectl installation link](https://kubernetes.io/docs/tasks/tools/install-kubectl/).\n\n## Setup pre-requisite services\n\nThis repo contains 4 scripts for setting up, respectively cleaning up pre-requisite tolls and Spring Boot microservices for usage with the TODOS-API application.\n\n```shell\n# Please validate that the downloaded scripts are executable\n# Otherwise, in the /setup folder, execute\ncd setup\nchmod +x *\n \n# Setup - please run in order\n./install-tools.sh -- Helm chart based installer for caching and database\ncd setup\n./setup-app.sh -- kubectl-based deployment for 4 services for the TODO app\n\n# installation can be validated by checking all running services in K8s\nkubectl get services\n\n# Ex.:\nNAME                                TYPE           CLUSTER-IP    EXTERNAL-IP       PORT(S)          AGE\nkubernetes                          ClusterIP      10.0.0.1      \u003cnone\u003e            443/TCP          93d\ntodo-mysql-instance-mariadb         ClusterIP      10.0.12.243   \u003cnone\u003e            3306/TCP         3d22h\ntodo-mysql-instance-mariadb-slave   ClusterIP      10.0.1.47     \u003cnone\u003e            3306/TCP         3d22h\ntodo-redis-instance-headless        ClusterIP      None          \u003cnone\u003e            6379/TCP         3d22h\ntodo-redis-instance-master          ClusterIP      10.0.0.20     \u003cnone\u003e            6379/TCP         3d22h\ntodo-redis-instance-slave           ClusterIP      10.0.3.76     \u003cnone\u003e            6379/TCP         3d22h\ntodos-mysql                         LoadBalancer   10.0.1.43     35.223.204.37     9090:30207/TCP   47h\ntodos-redis                         LoadBalancer   10.0.14.98    104.154.253.234   8888:31530/TCP   47h\ntodos-service                       LoadBalancer   10.0.11.54    35.225.226.171    9999:30011/TCP   47h\ntodos-webui                         LoadBalancer   10.0.14.60    104.197.8.27      8080:30908/TCP   47h\n\n# Cleanup - please run in order\n./cleanup-tools.sh -- Helm chart based installer for caching and database\n./remove-app.sh -- kubectl-based removal for 4 services for the TODO app\n```\n\n## Compiling and Building and Image for the TODOS-API\nThe application is configured by default with Java 11 in the Maven pom.xml file. You can update it to Java 16 if you choose to do so.\n\n__Local development__\n\nThe app can be built and started locally from the command-line or from withing an IDE\n```shell\n./mvnw clean package\n```\n\n__Images__\n\nTo build and run Docker images, start clean by checking that no todos-api images exist on your machine by executing\n```shell\ndocker images | grep todos-api | awk '{print $3}' | xargs docker rmi -f\n```\n\nTo compile the code and build an image for ```todos-api```, this repo illustrates 3 methods. \n\nA pre-built image has already been provisioned in Docker Hub at this [todos-api link](https://hub.docker.com/repository/docker/triathlonguy/todos-api) and can be retrieved by executing ```docker pull triathlonguy/todos-api:latest```\n\n__1. Spring Boot image builder - as of Spring 2.3.x, uses Paketo buildpacks__\n```shell\nmvn clean spring-boot:build-image\n\n# validate image creation\ndocker images | grep todos-api\n```\n\n__2. Skaffold__\n```shell\n# builds the image only\nskaffold build\n\n# validate image creation\ndocker images | grep todos-api\n```\n\n## Running TODOS-API in a local environment\nThe app can be built and started locally from the command-line or from withing an IDE\n```shell\n./mvnw clean package\njava -jar target/todos-api-1.4.0.jar \n\n# requests can be sent to localhost:8082\n# /src/main/resources/application.yaml needs to be updated with the endpoints of the cache, respectively database\n```\n\n## Deploying TODOS-API in Kubernetes using kubectl\nThe app can be deployed and started in any Kubernetes environment using kubectl \n```shell\nkubectl apply -f kubernetes/app\n```\n\nRemoving the ```todos-api``` deployment can be done by executing\n```shell\nkubectl delete -f kubernetes/app\n```\n\n## Deploying, Developing \u0026 Debugging in Kubernetes with Skaffold\nSkaffold is a command line tool that facilitates continuous development for Kubernetes applications. It simplifies the development process by combining multiple steps into one easy command and provides the building blocks for a CI/CD process.\n\nDevelopers can use Skaffold to manage the development lifecycle of the todos-api by executing\n```shell\nskaffold dev \n```\n\nSkaffold builds the application, deploys it and monitors for any changes. If any file is changed, from an IDE or text editor, Skaffold will trigger a fresh build and deploy process.\n\nTo end the working session, just press CTRL-C in the terminal window from where the Skaffold command has been executed. Skaffold will clean up all deployed artifacts.\n\nSkaffold allows developers to have remote debugging sessions in Kubernetes, by executing\n```shell\nskaffold debug --port-forward -f skaffold.yaml \n```\n\nSkaffold will forward port 5005, where a remote debugging session can be setup in IntelliJ/Eclipse/VSCode. \n\nPlease set up a remote session in your favorite IDE at port 5005, set up breakpoints and send HTTP requests to the API at the configured for this app (8080 is the default).\n\nIDEs indicate when the remote connection has been established:\n```code\nConnected to the target VM, address: 'localhost:5005', transport: 'socket'\n```\n\n\n## Deploying, Developing \u0026 Debugging in Kubernetes with Externalized Configurations using Skaffold \u0026 Kustomize\n* One of the [12 factors for cloud native apps is to externalize configuration](https://12factor.net/config)\n* Kubernetes provides support for externalizing configuration via config maps and secrets\n* A config map or secret can easily be created using kubectl\n* Kustomize offers a much improved way of generating config maps and secrets as part of our customizations to different environments, which can be versioned and managed in Source Control\n\nKustomize features\n* Allows easier deployments to different environments/providers\n* Allows you to keep all the common properties in one place\n* Generate configuration for specific environments\n* No templates, no placeholder spaghetti, no environment variable overload\n\nFor example, if we wish to deploy the app to a QA environment, we wish to customize some of the configuration. \n\nThis repo has an example of a QA environment which scales the todos-api to 2 replicas, as per the ```update-replicas.yaml``` customization file made available in ```/kubernetes/overlays/qa```\n\nDeploy the ```todos-api``` using Skaffolf + Kustomize for the imaginary QA environment by executing\n```shell\nskaffold dev -p qa\n\n# note that the skaffold.yaml file is not specified, as Skaffold looks by default for a file called skaffold.yaml, which is availalble in this repo\n\n# observe that 2 replicas of the todos-api have been created\npod/todos-api-7f795466ff-7gp5w             1/1     Running   0          9s\npod/todos-api-7f795466ff-k9jkx             1/1     Running   0          10s\n```\n\n## Usage Examples for Application \u0026 Actuator endpoints\nOnce the app is deployed in Kubernetes, please retrieve the endpoint at which ```todos-api``` is exposed\n```shell\nkubectl get svc\n\n# example\nNAME      TYPE           CLUSTER-IP    EXTERNAL-IP       PORT(S)          AGE\ntodos-api LoadBalancer   10.0.13.177   35.193.98.123     8082:31783/TCP   15m\n```\nTo ```add a new TODO item```, say ```todo0``` execute:\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082 completed=false title=todo0 category=personal deadline=2020/10/01\n\nhttp 35.193.98.123:8082 completed=false title=todo0 category=personal deadline=2020/10/01\n\n{\n    \"category\": \"personal\",\n    \"complete\": false,\n    \"deadline\": \"2020/10/01\",\n    \"id\": \"0d892025-8425-4af4-bf72-979a02b3d4bc\",\n    \"title\": \"todo0\"\n}\n```\n\nTo ```retrieve all TODO items``` execute:\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082\n\nhttp 35.193.98.123:8082\n# or \ncurl 35.193.98.123:8082\n\n[\n    {\n        \"category\": \"personal\",\n        \"complete\": false,\n        \"deadline\": \"2020/10/01\",\n        \"id\": \"0d892025-8425-4af4-bf72-979a02b3d4bc\",\n        \"title\": \"todo0\"\n    },\n    {\n        \"category\": \"Default group\",\n        \"complete\": false,\n        \"deadline\": \"2020/09/14\",\n        \"id\": \"cc56f488-57df-447d-a161-e59ed21bb230\",\n        \"title\": \"todo1\"\n    }\n]\n```\n\nTo ```retrieve a TODO item by {id}``` execute:\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082/{id}\n\nhttp 35.193.98.123:8082/0d892025-8425-4af4-bf72-979a02b3d4bc\n# or \ncurl 35.193.98.123:8082/0d892025-8425-4af4-bf72-979a02b3d4bc\n\n{\n    \"category\": \"personal\",\n    \"complete\": false,\n    \"deadline\": \"2020/10/01\",\n    \"id\": \"0d892025-8425-4af4-bf72-979a02b3d4bc\",\n    \"title\": \"todo0\"\n}\n```\n\nTo retrieve the ```customized Info Actuator``` data execute\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082/actuator/info\n\nhttp 35.193.98.123:8082/actuator/info\n# or\ncurl 35.193.98.123:8082/actuator/info\n\n{\n    \"app\": {\n        \"description\": \"TODOs - API - business logic w/ DB and cache access\",\n        \"name\": \"todos-api - Spring Boot Application\"\n    }\n}\n```\n\nTo retrieve the ```customized Health Actuator``` data execute\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082/actuator/health\n\nhttp 35.193.98.123:8082/actuator/health\n# or\ncurl 35.193.98.123:8082/actuator/health\n\n{\n    \"components\": {\n        \"customHealthCheck\": {\n            \"details\": {\n                \"Custom Health Check Status\": \"passed\"\n            },\n            \"status\": \"UP\"\n        },\n        \"diskSpace\": {\n            \"details\": {\n                \"exists\": true,\n                \"free\": 80728559616,\n                \"threshold\": 10485760,\n                \"total\": 101241290752\n            },\n            \"status\": \"UP\"\n        },\n        \"livenessState\": {\n            \"status\": \"UP\"\n        },\n        \"ping\": {\n            \"status\": \"UP\"\n        },\n        \"readinessState\": {\n            \"status\": \"UP\"\n        }\n    },\n    \"groups\": [\n        \"liveness\",\n        \"readiness\"\n    ],\n    \"status\": \"UP\"\n}\n```\n\nTo access a ```Custom Actuator``` introduced for educational purposes execute\n```shell\nhttp \u003cexternal_svc_ip\u003e:8082/actuator/custom\n\nhttp 35.193.98.123:8082/actuator/custom\n# or\ncurl 35.193.98.123:8082/actuator/custom\n\n{\n    \"CustomEndpoint\": \"Everything looks good at the custom endpoint\"\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddobrin%2Ftodos-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddobrin%2Ftodos-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddobrin%2Ftodos-api/lists"}