Simple Time Block API is a simple calendar event management microservice: create, read, update, and delete time-blocked calendar events. This project's purpose is to be a simple integration for people interested in a simple time blocking solution. The base application is programmed in Java, using the Spring Boot framework. The application utilizes Spring Data JPA to perform operations against a MySQL database. Unit testing for this API is in Groovy, using the Spock framework.

This section assumes that the user of this software has the knowledge of installing Java 17 and running maven-based Java applications. It also assumes that the user knows how to install and configure a MySQL database server.

• MySQL: With MySQL running, configure and run the setup_database.sql script to create the narlock-tb database.
• Run the application
  • Using Java 17: After building the application, navigate to the directory of the jar in a terminal and use java -jar simple-time-block-api.jar to run the application.
  • Using Maven: In a terminal, use mvn spring-boot:run to run the application.

This application creates both the integration layer (Simple Time Block API) as well as the backend database (narlock-tb Database).

The following is the database table represents an individual calendar event. When a calendar event is created, a unique id number will be assigned to it. There can be many calendar events that have the same start time and end time that are on the same day.

Guide

• Create a time-blocked event
• Create a recurring time-blocked event
• Overwrite an existing time-blocked event
• Update fields on an existing time-blocked event
• Delete an existing time-blocked event
• Delete time-blocked events on a given day
• Retrieve time-blocked events on a given day
• Retrieve a time-blocked event

The user can input the name of their event, a note, and the start time and end time of the event in the request payload. This will create the event and store it on the backend database. Name, start time, and end time are the only required fields for creating a time-blocked event. If the date parameter is not passed to the endpoint, the event will be created on the current local date.

POST /time-block
Content-Type: application/json

{
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

Response

HTTP/1.1 201 Created

{
   "id": 1,
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

Users can create a recurring time-blocked event based on a set of criteria.

• Repeat: When will this event reoccur?
  • DAILY, WEEKLY, or MONTHLY
• Until: How long events will be created after the start date.
  • WEEK, create events only up to the next seven days
  • MONTH, create events only up to the next 31 days
  • #MONTH, create events only up to the next # * 31 days, where # is a number 1-11 that represent the following # months.
  • YEAR, create events only up to the next 365 days

POST /time-block
Content-Type: application/json

{
   "repeat": "DAILY",
   "until": "YEAR",
   "event": {
      "name": "Yearly Eye Exam",
      "note": "123 John Doe Drive, Gotham City",
      "startTime": "16:00:00",
      "endTime": "16:30:00",
      "date": "2024-02-21",
      "meta": ""
   }
}

Response

HTTP/1.1 201 Created

{
   "count": 365,
   "startDate": "2024-02-21",
   "endDate": "2025-02-21"
}

The user can perform a full update on a time-blocked event. This means that every field is required to pass to overwrite.

PUT /time-block/{id}
Content-Type: application/json

{
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

Response

HTTP/1.1 200 OK

{
   "id": 1,
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

The user can overwrite specific fields of an existing time-blocked event. The parameters that are passed within the request payload will be updated for the given event id.

PATCH /time-block/{id}
Content-Type: application/json

{
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

Response

HTTP/1.1 200 OK

{
   "id": 1,
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}

The user can delete an existing time-blocked event.

DELETE /time-block/{id}

Response

HTTP/1.1 204 No Content

The user can delete all time-blocked events on a given day.

DELETE /time-block?day=yyyy-MM-dd

Response

HTTP/1.1 204 No Content

The user can retrieve all time-blocked events on a given day.

GET /time-block?day=yyyy-MM-dd
Content-Type: application/json

Response

HTTP/1.1 200 OK

{
   "date": "2024-02-21",
   "count": 2,
   "events": [
      {
         "id": 1,
         "name": "Yearly Eye Exam",
         "note": "123 John Doe Drive, Gotham City",
         "startTime": "16:00:00",
         "endTime": "16:30:00",
         "date": "2024-02-21",
         "meta": ""
      },
      {
         "id": 2,
         "name": "Study for English exam",
         "note": "",
         "startTime": "18:00:00",
         "endTime": "20:00:00",
         "date": "2024-02-21",
         "meta": ""
      },
   ]
}

The user can obtain a specific time-blocked event.

GET /time-block/{id}
Content-Type: application/json

Response

HTTP/1.1 200 OK

{
   "id": 1,
   "name": "Yearly Eye Exam",
   "note": "123 John Doe Drive, Gotham City",
   "startTime": "16:00:00",
   "endTime": "16:30:00",
   "date": "2024-02-21",
   "meta": ""
}