From 75539f5c4f9a62fb99dfa899ae252fece5ab05e5 Mon Sep 17 00:00:00 2001
From: Irina Batinic <irina.batinic@sonarsource.com>
Date: Wed, 6 Dec 2023 13:15:49 +0100
Subject: [PATCH] Add rule 6863: Set appropriate Status Codes on HTTP
 responses"

---
 rules/S6863/java/metadata.json | 12 +++----
 rules/S6863/java/rule.adoc     | 61 ++++++++++++++++++++++------------
 2 files changed, 45 insertions(+), 28 deletions(-)

diff --git a/rules/S6863/java/metadata.json b/rules/S6863/java/metadata.json
index fd1ef0fd1af..86bd6d35363 100644
--- a/rules/S6863/java/metadata.json
+++ b/rules/S6863/java/metadata.json
@@ -1,5 +1,5 @@
 {
-  "title": "FIXME",
+  "title": "Set appropriate Status Codes on HTTP responses",
   "type": "CODE_SMELL",
   "status": "ready",
   "remediation": {
@@ -7,19 +7,19 @@
     "constantCost": "5min"
   },
   "tags": [
+    "spring",
+    "best practice"
   ],
   "defaultSeverity": "Major",
   "ruleSpecification": "RSPEC-6863",
   "sqKey": "S6863",
-  "scope": "All",
+  "scope": "Main",
   "defaultQualityProfiles": ["Sonar way"],
   "quickfix": "unknown",
   "code": {
     "impacts": {
-      "MAINTAINABILITY": "HIGH",
-      "RELIABILITY": "MEDIUM",
-      "SECURITY": "LOW"
+      "MAINTAINABILITY": "LOW"
     },
-    "attribute": "CONVENTIONAL"
+    "attribute": "DISTINCT"
   }
 }
diff --git a/rules/S6863/java/rule.adoc b/rules/S6863/java/rule.adoc
index 4bd440f87a8..bad1425d41c 100644
--- a/rules/S6863/java/rule.adoc
+++ b/rules/S6863/java/rule.adoc
@@ -1,44 +1,61 @@
-FIXME: add a description
-
-// If you want to factorize the description uncomment the following line and create the file.
-//include::../description.adoc[]
-
 == Why is this an issue?
 
-FIXME: remove the unused optional headers (that are commented out)
+The request handler function in a `Controller` should set the appropriate HTTP status code based on the operation's success or failure.
+This is done by returning a `Response` object with the appropriate status code.
 
-//=== What is the potential impact?
+If an exception is thrown during the execution of the handler, the status code should be in the range of 4xx or 5xx.
+If no exception is thrown, the status code should be in the range of 2xx or 4xx.
 
 == How to fix it
-//== How to fix it in FRAMEWORK NAME
 
 === Code examples
 
 ==== Noncompliant code example
 
-[source,text,diff-id=1,diff-type=noncompliant]
+[source,java,diff-id=1,diff-type=noncompliant]
 ----
-FIXME
+@Controller
+public class UserController {
+    public ResponseEntity<User> getUserById(Long userId) {
+        try {
+            User user = userService.getUserById(userId);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(user); // Noncompliant: Setting 500 for a successful operation
+        } catch (NotFoundException e) {
+            return ResponseEntity.status(HttpStatus.OK).build(); // Noncompliant: Set 200 for resource not found
+        } catch (Exception e) {
+            return ResponseEntity.status(HttpStatus.NOT_FOUND).build(); // Noncompliant: Set 404 for other exceptions
+        }
+    }
+}
 ----
 
 ==== Compliant solution
 
-[source,text,diff-id=1,diff-type=compliant]
+[source,java,diff-id=1,diff-type=compliant]
 ----
-FIXME
+@Controller
+public class UserController {
+
+    public ResponseEntity<User> getUserById(Long userId) {
+        try {
+            User user = userService.getUserById(userId);
+            return ResponseEntity.ok(user); // Compliant: Set 200 for success
+        } catch (NotFoundException e) {
+            return ResponseEntity.status(HttpStatus.NOT_FOUND).build(); // Compliant: Set 404 for resource not found
+        } catch (Exception e) {
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build(); // Compliant: Set 500 for other exceptions
+        }
+    }
+}
 ----
 
-//=== How does this work?
+== Resources
 
-//=== Pitfalls
+=== Documentation
 
-//=== Going the extra mile
+* https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-methods/responseentity.html[Spring Framework Documentation - ResponseEntity]
+* https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html[Spring Framework Documentation - Exception Handling]
 
+=== Standards
 
-//== Resources
-//=== Documentation
-//=== Articles & blog posts
-//=== Conference presentations
-//=== Standards
-//=== External coding guidelines
-//=== Benchmarks
+* https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml[IANA - Hypertext Transfer Protocol (HTTP) Status Code Registry]