To-do List Project (WIP)

This is a hobby project which consists of an API REST Spring Boot based project.

I made this project firstly for training myself on new Java features like lambdas as well as for NoSQL database systems and Docker too.

In this case, I chose Cassandra DB for storing data.

---

Table of Contents

• To-do List Project (WIP)
  • Project Status
  • Running the application
  • Requisites (only for Docker deployment)
  • Requisites (only for local deployment)
  • Requisites
  • API Operations
  • Examples
    • Save item
      • Success response
      • Error response
    • Save an items collection
      • Success response
      • Error response
      • Error response
    • Delete item
      • Success response
      • Error response
      • Error response
    • Delete all items
      • Success response
    • Retrieve all items
      • Success response
    • Update item
      • Success response
      • Error response
      • Error response
    • Swagger
  • Technologies
  • Tools
  • License

---

Project Status

• App Dockerized.
• Aspect for logging public controller methods.
• Authorization.
• Caching with Redis (some operations only).
• CRUD operations for a to-do list.
• Exception handling with controller advice.
• Jenkins basic pipeline.
• Kafka integration for massive creation operations.
• Request data validation.
• Spring Actuator (default configuration).
• Spring HATEOAS.
• Spring WebFlux.
• Support for Cassandra DB.
• Swagger for API documentation.
• Travis basic pipeline.
• Unit tests.

---

Running the application

This app is dockerized. This mean that the only things you have to do is clone this repo and run the following command on the project root to create the Docker image of the project):

mvn clean package dockerfile:build

The mvnw wrapper is available if you don't want to install Maven:

./mvnw clean package dockerfile:build

After that, you can have all up and running by executing the following command:

docker-compose up

You can run this app locally too, but you have to manually configure all the dependencies described on the Requisites (only for local deployment) section.

---

Requisites (only for Docker deployment)

The only requisite is have installed Docker and Docker-compose. Maven is an optional requisite because you can use the provided Maven wrapper instead.

---

Requisites (only for local deployment)

You must have Redis, Cassandra DB and a Kafka instance properly configured. Please, configure the project's properties according to your configuration modifying theapplication.yamlfile.

The following are the properties you can configure for this application:

spring:
  data:
    cassandra:
      contact-points: localhost
      keyspace-name: todoList
      schema-action: CREATE_IF_NOT_EXISTS

  kafka:
    consumer:
      group-id: group-id
    template:
      default-topic: todoListUsers

  redis:
    host: localhost

  cache:
    redis:
      time-to-live: 600000

---

API Operations

The following is a list of supported operations:

• Save a to-do item:POST /v1/todo-list/items
• Save a collection of to-do item:POST /v1/todo-list/batch/items
• Delete a to-do item:DELETE /v1/todo-list/items/{id}
• Delete all to-do items:DELETE /v1/todo-list/items
• Retrieve a to-do item:GET /v1/todo-list/items/{id}
• Retrieve all to-do items:GET /v1/todo-list/items
• Update a to-do item:PATCH /v1/todo-list/items

---

Examples

Save item

Used to persist a to-do item on database.

URL: /v1/todo-list/items

Method: POST

Auth required: No.

Data constraints:

{
	"description": "[Valid text, not null or empty]"
}

Data example:

{
	"description": "To do item example"
}

Success response

Code: 201 CREATED

Content:

{
  "id": "[Valid UUID value]",
	"description": "[Valid text]",
  "status": "Created",
  "createdDateTime": "[yyyy mm dd HH:MM:SS]"
}

Data example:

{
	"id": "a056fb54-317e-4982-bd83-ccb0b8b97d74",
  "description": "To do item example",
  "status": "Created",
  "createdDateTime": "2019 11 04 16:50:00"
}

Error response

Code: 400 BAD REQUEST

Condition: If 'description' is null or empty.

Content:

{
    "errorMessages": [
        "Description can not be null or empty"
    ]
}

---

Save an items collection

Used to persist a to-do items collection on database.

URL: /v1/todo-list/batch/items

Method: POST

Auth required: No.

Data constraints:

[
  {
    "description": "[Valid text, not null or empty]"
  },
  {
    "description": "[Valid text, not null or empty]"
  }
]

Data example:

[
  {
		"description": "To do item example"
	},
  {
		"description": "To do item example 2"
	}
]

Success response

Code: 201 CREATED

Content:

[
  {
    "id": "[Valid UUID value]",
		"description": "[Valid text]",
  	"status": "Created",
	  "createdDateTime": "[yyyy mm dd HH:MM:SS]"
	},
  {
    "id": "[Valid UUID value]",
		"description": "[Valid text]",
  	"status": "Created",
	  "createdDateTime": "[yyyy mm dd HH:MM:SS]"
	}
]

Data example:

[
  {
    "id": "a056fb54-317e-4982-bd83-ccb0b8b97d74",
    "description": "To do item example",
    "status": "Created",
    "createdDateTime": "2019 11 04 16:50:00"
  },
  {
    "id": "a056fb54-317e-4982-bd83-ccb0b8b97d74",
    "description": "To do item example 2",
    "status": "Created",
    "createdDateTime": "2019 11 04 16:50:01"
  }
]

Error response

Code: 400 BAD REQUEST

Condition: If request body is missing.

Content:

{
    "errorMessages": [
        "Empty request"
    ]
}

Error response

Code: 400 BAD REQUEST

Condition: If 'id' or 'description' are null or empty.

Content:

{
    "errorMessages": {
        "0": [
            "Description can not be null or empty",
            "Id can not be null"
        ]
    }
}

---

Delete item

Used to delete a specific to-do item on database.

URL: /v1/todo-list/items/{id}

Method: DELETE

Auth required: No.

Data constraints:

{id} must be a valid UUID value.

Data example:

/todoList/items/a056fb54-317e-4982-bd83-ccb0b8b97d74

Success response

Code: 204 NO CONTENT

Content: No.

Error response

Code: 400 BAD REQUEST

Condition: Sending a non UUID id param.

Content:

{
    "errorMessages": [
        "Argument type mismatch. Please check data types and try again."
    ]
}

Error response

Code: 400 BAD REQUEST

Condition: Deleting an inexistent item.

Content:

{
    "errorMessages": [
        "Entity not found."
    ]
}

---

Delete all items

Used to delete all to-do items saved on database.

URL: /v1/todo-list/items

Method: DELETE

Auth required: No.

Data constraints: No.

Data example: No.

Success response

Code: 204 NO CONTENT

Content: No.

---

Retrieve all items

Used to retrieve all to-do items on database.

URL: /v1/todo-list/items

Method: GET

Auth required: No.

Data constraints: No.

Success response

Code: 200 OK

Content: A collection of items.

[
  {
    "id": "a056fb54-317e-4982-bd83-ccb0b8b97d74",
    "description": "To do item example",
    "createdDatetime": "2019 26 25 11:07:03",
    "status": "Created"
  },
  {
    "id": "a056fb54-317e-4982-bd83-ccb0b8b97d73",
    "description": "To do item example 2",
    "createdDatetime": "2019 57 25 11:07:49",
    "status": "In Progress"
  }
]

---

Update item

Used to update a to-do item saved on database.

URL: /v1/todo-list/items

Method: PATCH

Auth required: No.

Data constraints:

{
	"id": "[Valid UUID value]",
	"description": "[Valid text, not null or empty]",
  "status": "[Created, In Progress, Done]"
}

Data example:

{
	"id": "a056fb54-317e-4982-bd83-ccb0b8b97d73",
	"description": "New description",
  "status": "Done"
}

Success response

Code: 204 NO CONTENT

Content: No.

Error response

Code: 400 BAD REQUEST

Condition: If 'id', 'description' or 'status' are null, empty or invalid.

Content:

{
  "errorMessages": [
    "Description can not be null or empty",
    "Id can not be null",
    "Status can not be null"
  ]
}

Error response

Code: 400 BAD REQUEST

Condition: Updating an inexistent item.

Content:

{
    "errorMessages": [
        "Entity not found."
    ]
}

---

Swagger

Here is the Swagger-generated API documentation. The project has to be running to access the page.

---

Technologies

This project uses the following technologies:

• Apache Cassandra DB.
• Apache Kafka.
• Docker.
• Java.
• Maven.
• Redis.
• Spring Boot.
• Swagger.

---

Tools

This project was made using the following tools:

• Code Climate.
• Codecov.
• Conventional Commits.
• gh-md-toc
• Gitignore.io.
• IntelliJ IDEA.
• Open Source Badges.
• Postman.
• Snyk io.
• Travis CI.
• Typora.

---

License

GNU GPL 3.0