[API] Visit patch request to start next stage

CHANGELOG.md

@@ -34,6 +34,7 @@ requesting a new account and will be displayed in the User Accounts module (PR #
 #### API
 - Creation of a new version of the API under development (v0.0.4-dev) (PR #6944)
 - Deletion of support for the oldest version of the API (v0.0.2) (PR #6944)
+- Addition of a PATCH request for /candidates/$CandID/$VisitLabel to start next stage when the payload contains a "Visit" stage with "In Progress" as Status, when the current status of the Visit stage is "Not Started". (PR #7479)
 #### Candidate Parameters
 - Consents may now be grouped in UI of consent tab (PR #6042, PR #6044)
 #### API Documentation (**New Module**)

modules/api/docs/LorisRESTAPI.md

@@ -416,7 +416,7 @@ The JSON object is of the form:
 }
 ```
 
-A PUT of the same format but with only the Meta fields will create the VisitLabel
+A PUT request with only the Meta fields will create the VisitLabel
 for this candidate, in an unstarted stage if the Visit label provided is valid.
 
 PATCH is not supported for Visit Labels.

modules/api/docs/LorisRESTAPI_v0.0.4-dev.md

@@ -416,10 +416,27 @@ The JSON object is of the form:
 }
 ```
 
-A PUT of the same format but with only the Meta fields will create the VisitLabel
+A PUT request with only the Meta fields will create the VisitLabel
 for this candidate, in an unstarted stage if the Visit label provided is valid.
 
-PATCH is not supported for Visit Labels.
+A PATCH request of the form:
+```js
+{
+    "CandID"  : 317604,
+    "Visit"   : 'Visit 01',
+    "Site"    : 'DCC',
+    "Battery" : 'Stale',
+    "Project" : 'Pumpernickel',
+    "Stages" : {
+        "Visit" : {
+            "Date" : "YYYY-MM-DD",
+            "Status" : "In Progress"
+        }
+    }
+}
+```
+will update the Visit stage date and status and start the next stage if the Visit stage
+is 'Not Started' and the CandID and Visit label provided are valid.
 
 It will return a 404 Not Found if the visit label does not exist for this candidate
 (as well as anything under the /candidates/$CandID/$VisitLabel hierarchy)

modules/api/php/endpoints/candidate/candidate.class.inc

@@ -95,7 +95,7 @@ class Candidate extends Endpoint implements \LORIS\Middleware\ETagCalculator
         }
 
         // Delegate to sub-endpoints
-        $visit_label = array_shift($pathparts);
+        $visit_label = urldecode(array_shift($pathparts));
         $newrequest  = $request
             ->withAttribute('pathparts', $pathparts);
 
@@ -112,7 +112,14 @@ class Candidate extends Endpoint implements \LORIS\Middleware\ETagCalculator
             $visit = null;
         }
 
-        $handler = new Visit\Visit(
+        $version     = $request->getAttribute("LORIS-API-Version");
+        $subendpoint = __NAMESPACE__ . '\\' . 'Visit\Visit';
+
+        if ($version == 'v0.0.4-dev') {
+            $subendpoint = __NAMESPACE__ . '\\' .'Visit\Visit_0_0_4_Dev';
+        }
+
+        $handler = new $subendpoint(
             $this->_candidate,
             $visit
         );

modules/api/php/endpoints/candidate/visit/visit.class.inc

@@ -77,7 +77,6 @@ class Visit extends Endpoint implements \LORIS\Middleware\ETagCalculator
     {
          return [
              'v0.0.3',
-             'v0.0.4-dev',
          ];
     }
 
@@ -215,7 +214,7 @@ class Visit extends Endpoint implements \LORIS\Middleware\ETagCalculator
 
         if ($visitinfo['CandID'] !== $this->_candidate->getCandID()) {
             return new \LORIS\Http\Response\JSON\BadRequest(
-                'CandID do not match this candidate'
+                'CandID does not match this candidate'
             );
         }