Yana P.

task-1/API_DESIGN.md

@@ -0,0 +1,188 @@
+# API_DESIGN.md
+
+# Analytics API — Design Document
+
+This document describes the design of the Analytics API, including resources, supported actions, request bodies, response bodies, status codes, validation rules, and error responses.
+
+---
+
+## 1. Resource Model
+
+AnalyticsRecord contains:
+- timestamp (Instant)
+- eventType (String)
+- eventSource (String)
+- sessionId (String)
+- traceId (UUID, generated by the server)
+
+---
+
+## 2. Endpoints
+
+Base path: /records
+
+---
+
+## 2.1 Create a new analytics record
+POST /records
+
+Request body:
+{
+"timestamp": "2024-01-01T12:00:00Z",
+"eventType": "CLICK",
+"eventSource": "frontend",
+"sessionId": "abc123xyz"
+}
+
+Validation rules:
+- timestamp: required, not null
+- eventType: required, not blank
+- eventSource: required, not blank
+- sessionId: required, 6–64 characters
+
+Responses:
+201 Created  
+Body:
+{
+"timestamp": "...",
+"eventType": "...",
+"eventSource": "...",
+"sessionId": "...",
+"traceId": "generated-uuid"
+}
+Header: Location: /records/{traceId}
+
+400 Bad Request (validation errors):
+{
+"eventType": "Event type is required.",
+"sessionId": "Session id must be between 6 and 64 symbols."
+}
+
+---
+
+## 2.2 List analytics records
+GET /records
+
+Optional filters:
+- timeStart (Instant)
+- timeEnd (Instant)
+- eventType (String)
+- eventSource (String)
+- sessionId (String)
+
+Response 200 OK:
+[
+{
+"timestamp": "...",
+"eventType": "...",
+"eventSource": "...",
+"sessionId": "...",
+"traceId": "..."
+}
+]
+
+---
+
+## 2.3 Fetch a single record
+GET /records/{traceId}
+
+Responses:
+200 OK:
+{
+"timestamp": "...",
+"eventType": "...",
+"eventSource": "...",
+"sessionId": "...",
+"traceId": "..."
+}
+
+404 Not Found:
+{}
+
+---
+
+## 2.4 Replace a record
+PUT /records/{traceId}
+
+Request body: same as POST.
+
+Responses:
+200 OK:
+{
+"timestamp": "...",
+"eventType": "...",
+"eventSource": "...",
+"sessionId": "...",
+"traceId": "..."
+}
+
+404 Not Found:
+{}
+
+400 Bad Request (validation errors):
+{
+"eventType": "Event type is required.",
+"sessionId": "Session id must be between 6 and 64 symbols."
+}
+
+---
+
+## 2.5 Delete a record
+DELETE /records/{traceId}
+
+Responses:
+204 No Content  
+(no body)
+
+404 Not Found:
+{}
+
+---
+
+## 2.6 Summary
+GET /records/summary
+
+Response 200 OK:
+{
+"totalRecords": 42,
+"eventsByType": {
+"CLICK": 20,
+"LOGIN": 22
+},
+"uniqueSessions": 12
+}
+
+---
+
+## 3. Error Handling
+
+Validation errors → 400 Bad Request:
+{
+"timestamp": "Timestamp is required.",
+"eventType": "Event type is required."
+}
+
+General errors → 400 Bad Request:
+{
+"error": "Some error message"
+}
+
+---
+
+## 4. Status Code Summary
+
+POST /records → 201 or 400  
+GET /records → 200  
+GET /records/{id} → 200 or 404  
+PUT /records/{id} → 200 or 400 or 404  
+DELETE /records/{id} → 204 or 404  
+GET /records/summary → 200
+
+---
+
+## 5. Notes
+
+- Controllers are thin and delegate logic to the service layer.
+- Validation uses Bean Validation annotations.
+- Errors are returned as structured JSON via GlobalExceptionHandler.
+

task-1/HELP.md

@@ -0,0 +1,28 @@
+# Getting Started
+
+### Reference Documentation
+For further reference, please consider the following sections:
+
+* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
+* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/4.0.6/maven-plugin)
+* [Create an OCI image](https://docs.spring.io/spring-boot/4.0.6/maven-plugin/build-image.html)
+* [Spring Web](https://docs.spring.io/spring-boot/4.0.6/reference/web/servlet.html)
+* [Validation](https://docs.spring.io/spring-boot/4.0.6/reference/io/validation.html)
+* [SpringDoc OpenAPI](https://springdoc.org/)
+
+### Guides
+The following guides illustrate how to use some features concretely:
+
+* [Building a RESTful Web Service](https://spring.io/guides/gs/rest-service/)
+* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/)
+* [Building REST services with Spring](https://spring.io/guides/tutorials/rest/)
+* [Validation](https://spring.io/guides/gs/validating-form-input/)
+* [SpringDoc OpenAPI](https://github.com/springdoc/springdoc-openapi-demos/)
+
+### Maven Parent overrides
+
+Due to Maven's design, elements are inherited from the parent POM to the project POM.
+While most of the inheritance is fine, it also inherits unwanted elements like `<license>` and `<developers>` from the parent.
+To prevent this, the project POM contains empty overrides for these elements.
+If you manually switch to a different parent and actually want the inheritance, you need to remove those overrides.
+