From 42f86a4a24ad9c683a5c4c388921821c5cb64e9e Mon Sep 17 00:00:00 2001
From: Alejandro Celaya <alejandro@alejandrocelaya.com>
Date: Sat, 22 Oct 2016 18:46:53 +0200
Subject: [PATCH] Added versioning to API endpoints, allowing not to pass the
 version which will default to v1

---
 docs/swagger.json                             | 10 ++--
 module/Rest/config/dependencies.config.php    |  1 +
 .../config/middleware-pipeline.config.php     |  7 +++
 module/Rest/config/routes.config.php          | 12 ++---
 .../src/Middleware/PathVersionMiddleware.php  | 54 +++++++++++++++++++
 5 files changed, 73 insertions(+), 11 deletions(-)
 create mode 100644 module/Rest/src/Middleware/PathVersionMiddleware.php

diff --git a/docs/swagger.json b/docs/swagger.json
index fea8a020..262b0cfc 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -14,7 +14,7 @@
     ],
 
     "paths": {
-        "/authenticate": {
+        "/v1/authenticate": {
             "post": {
                 "description": "Performs an authentication",
                 "parameters": [
@@ -60,7 +60,7 @@
                 }
             }
         },
-        "/short-codes": {
+        "/v1/short-codes": {
             "get": {
                 "description": "Returns the list of short codes",
                 "parameters": [
@@ -185,7 +185,7 @@
                 }
             }
         },
-        "/short-codes/{shortCode}": {
+        "/v1/short-codes/{shortCode}": {
             "get": {
                 "description": "Get the long URL behind a short code.",
                 "parameters": [
@@ -234,7 +234,7 @@
                 }
             }
         },
-        "/short-codes/{shortCode}/visits": {
+        "/v1/short-codes/{shortCode}/visits": {
             "get": {
                 "description": "Get the list of visits on provided short code.",
                 "parameters": [
@@ -284,7 +284,7 @@
                 }
             }
         },
-        "/short-codes/{shortCode}/tags": {
+        "/v1/short-codes/{shortCode}/tags": {
             "put": {
                 "description": "Edit the tags on provided short code.",
                 "parameters": [
diff --git a/module/Rest/config/dependencies.config.php b/module/Rest/config/dependencies.config.php
index a6b51cb7..3fae9af7 100644
--- a/module/Rest/config/dependencies.config.php
+++ b/module/Rest/config/dependencies.config.php
@@ -22,6 +22,7 @@ return [
 
             Middleware\BodyParserMiddleware::class => AnnotatedFactory::class,
             Middleware\CrossDomainMiddleware::class => InvokableFactory::class,
+            Middleware\PathVersionMiddleware::class => InvokableFactory::class,
             Middleware\CheckAuthenticationMiddleware::class => AnnotatedFactory::class,
         ],
     ],
diff --git a/module/Rest/config/middleware-pipeline.config.php b/module/Rest/config/middleware-pipeline.config.php
index ce22dff1..8adea240 100644
--- a/module/Rest/config/middleware-pipeline.config.php
+++ b/module/Rest/config/middleware-pipeline.config.php
@@ -4,6 +4,13 @@ use Shlinkio\Shlink\Rest\Middleware;
 return [
 
     'middleware_pipeline' => [
+        'pre-routing' => [
+            'middleware' => [
+                Middleware\PathVersionMiddleware::class,
+            ],
+            'priority' => 11,
+        ],
+
         'rest' => [
             'path' => '/rest',
             'middleware' => [
diff --git a/module/Rest/config/routes.config.php b/module/Rest/config/routes.config.php
index d27b9c6d..8d107d8b 100644
--- a/module/Rest/config/routes.config.php
+++ b/module/Rest/config/routes.config.php
@@ -6,37 +6,37 @@ return [
     'routes' => [
         [
             'name' => 'rest-authenticate',
-            'path' => '/rest/authenticate',
+            'path' => '/rest/v{version:1}/authenticate',
             'middleware' => Action\AuthenticateAction::class,
             'allowed_methods' => ['POST', 'OPTIONS'],
         ],
         [
             'name' => 'rest-create-shortcode',
-            'path' => '/rest/short-codes',
+            'path' => '/rest/v{version:1}/short-codes',
             'middleware' => Action\CreateShortcodeAction::class,
             'allowed_methods' => ['POST', 'OPTIONS'],
         ],
         [
             'name' => 'rest-resolve-url',
-            'path' => '/rest/short-codes/{shortCode}',
+            'path' => '/rest/v{version:1}/short-codes/{shortCode}',
             'middleware' => Action\ResolveUrlAction::class,
             'allowed_methods' => ['GET', 'OPTIONS'],
         ],
         [
             'name' => 'rest-list-shortened-url',
-            'path' => '/rest/short-codes',
+            'path' => '/rest/v{version:1}/short-codes',
             'middleware' => Action\ListShortcodesAction::class,
             'allowed_methods' => ['GET'],
         ],
         [
             'name' => 'rest-get-visits',
-            'path' => '/rest/short-codes/{shortCode}/visits',
+            'path' => '/rest/v{version:1}/short-codes/{shortCode}/visits',
             'middleware' => Action\GetVisitsAction::class,
             'allowed_methods' => ['GET', 'OPTIONS'],
         ],
         [
             'name' => 'rest-edit-tags',
-            'path' => '/rest/short-codes/{shortCode}/tags',
+            'path' => '/rest/v{version:1}/short-codes/{shortCode}/tags',
             'middleware' => Action\EditTagsAction::class,
             'allowed_methods' => ['PUT', 'OPTIONS'],
         ],
diff --git a/module/Rest/src/Middleware/PathVersionMiddleware.php b/module/Rest/src/Middleware/PathVersionMiddleware.php
new file mode 100644
index 00000000..b3eae299
--- /dev/null
+++ b/module/Rest/src/Middleware/PathVersionMiddleware.php
@@ -0,0 +1,54 @@
+<?php
+namespace Shlinkio\Shlink\Rest\Middleware;
+
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Zend\Stratigility\MiddlewareInterface;
+
+class PathVersionMiddleware implements MiddlewareInterface
+{
+    /**
+     * Process an incoming request and/or response.
+     *
+     * Accepts a server-side request and a response instance, and does
+     * something with them.
+     *
+     * If the response is not complete and/or further processing would not
+     * interfere with the work done in the middleware, or if the middleware
+     * wants to delegate to another process, it can use the `$out` callable
+     * if present.
+     *
+     * If the middleware does not return a value, execution of the current
+     * request is considered complete, and the response instance provided will
+     * be considered the response to return.
+     *
+     * Alternately, the middleware may return a response instance.
+     *
+     * Often, middleware will `return $out();`, with the assumption that a
+     * later middleware will return a response.
+     *
+     * @param Request $request
+     * @param Response $response
+     * @param null|callable $out
+     * @return null|Response
+     */
+    public function __invoke(Request $request, Response $response, callable $out = null)
+    {
+        $uri = $request->getUri();
+        $path = $uri->getPath();
+
+        // If the path does not begin with the version number, prepend v1 by default for retrocompatibility purposes
+        if (strpos($path, '/rest/v') !== 0) {
+            $parts = explode('/', $path);
+            // Remove the first empty part and the "/rest" prefix
+            array_shift($parts);
+            array_shift($parts);
+            // Prepend the prefix with version
+            array_unshift($parts, '/rest/v1');
+
+            $request = $request->withUri($uri->withPath(implode('/', $parts)));
+        }
+
+        return $out($request, $response);
+    }
+}