JSON API: New Version Endpoint (#3140)

* Implementation

* Update API docs

Author: pglombardo

app/controllers/api/base_controller.rb

@@ -11,6 +11,10 @@ def require_api_authentication
     if (user = user_from_token)
       sign_in user, store: false
 
+    elsif params["controller"] == "api/v1/version"
+      # Version endpoint is public
+      nil
+
     elsif request.headers.key?("Authorization") || request.headers.key?("X-User-Token")
       # The user is trying to authenticate with a bad token
       head :unauthorized

app/controllers/api/v1/version_controller.rb

@@ -0,0 +1,30 @@
+class Api::V1::VersionController < Api::BaseController
+  api :GET, "/api/v1/version.json", "Get the version details of the application and the API."
+  formats ["JSON"]
+  description <<-EOS
+    == Version Information
+
+    Retrieves the current application version, API version, edition and other information.
+
+    === Example Request
+
+      curl -X GET \\
+        -H "Authorization: Bearer MyAPIToken" \\
+        https://pwpush.com/api/v1/version.json
+
+    === Example Response
+
+      {
+        "application_version": "2.1.0",
+        "api_version": "1",
+        "edition": "oss"
+      }
+  EOS
+  def show
+    render json: {
+      application_version: Version.current.to_s,
+      api_version: Apipie.configuration.default_version,
+      edition: "oss"
+    }
+  end
+end

config/initializers/apipie.rb

@@ -4,11 +4,11 @@
   config.app_name = "Password Pusher"
   config.copyright = "© 2011-Present Peter Giacomo Lombardo"
   config.api_base_url = ""
-  config.api_base_url["1.3"] = ""
+  config.api_base_url["1.4"] = ""
   config.doc_base_url = "/api"
   config.api_controllers_matcher = Rails.root.join("app/controllers/**/*.rb").to_s
   config.validate = false
-  config.default_version = "1.3"
+  config.default_version = "1.4"
   config.app_info = <<-APPINFO
     The Password Pusher JSON API.
 
@@ -31,7 +31,12 @@
 
     For more information including language-specific examples to copy, see: https://docs.pwpush.com/docs/json-api/
 
-    == February 2025 Update
+    == February 2025 Update (v1.4)
+
+    Added a new version endpoint to get the current application version, API version, and edition information.  This will be expanded
+    soon to include more information.
+
+    == February 2025 Update (v1.3)
 
     The API has been updated to use Bearer tokens for authentication and a general cleanup of the API.
 

config/routes.rb

@@ -11,7 +11,8 @@
     draw :admin
     draw :users
     draw :pushes
-    draw :pushes_api
+    draw :pwp_api
+
     apipie
 
     get "/pages/*id" => "pages#show", :as => :page, :format => false

config/routes/pushes_api.rb config/routes/pwp_api.rb

@@ -1,4 +1,10 @@
 constraints(format: :json) do
+  namespace :api do
+    namespace :v1 do
+      get :version, to: "version#show"
+    end
+  end
+
   resources :p, controller: "api/v1/passwords", as: :passwords, except: %i[new index edit update] do
     get "preview", on: :member
     get "audit", on: :member

test/fixtures/users.yml

@@ -9,7 +9,12 @@ luca:
   encrypted_password: $2a$12$mvenK9BFqCuzPIg.gV.u8egtR4iyNGgrHtQHX5g9E6I5Ehrz4cCD6
   confirmed_at: 2021-01-01 00:00:00
   authentication_token: 1234567890
-  confirmed_at: 2021-01-01 00:00:00
+
+one:
+  email: [email protected]
+  encrypted_password: <%= Devise::Encryptor.digest(User, 'password12345') %>
+  confirmed_at: 2025-02-28 18:00:00
+  authentication_token: 0987654321
 
 two:
   email: [email protected]

test/integration/api/api_version_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class VersionEndpointTest < ActionDispatch::IntegrationTest
+  def test_anonymous_version_endpoint
+    get "/api/v1/version.json"
+    assert_response :success
+    assert_equal Version.current.to_s, JSON.parse(@response.body)["application_version"]
+    assert_equal Apipie.configuration.default_version, JSON.parse(@response.body)["api_version"]
+    assert_equal "oss", JSON.parse(@response.body)["edition"]
+
+    get "/api/v1/version"
+    assert_response :success
+    assert_equal Version.current.to_s, JSON.parse(@response.body)["application_version"]
+    assert_equal Apipie.configuration.default_version, JSON.parse(@response.body)["api_version"]
+    assert_equal "oss", JSON.parse(@response.body)["edition"]
+  end
+
+  def test_authenticated_version_endpoint
+    @user_one = users(:one)
+    sign_in @user_one
+
+    get "/api/v1/version.json",
+      headers: {
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{@user_one.authentication_token}"
+      }
+
+    assert_response :success
+    assert_equal Version.current.to_s, JSON.parse(@response.body)["application_version"]
+    assert_equal Apipie.configuration.default_version, JSON.parse(@response.body)["api_version"]
+    assert_equal "oss", JSON.parse(@response.body)["edition"]
+
+    @user_one = users(:one)
+    sign_in @user_one
+
+    get "/api/v1/version",
+      headers: {
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{@user_one.authentication_token}"
+      }
+
+    assert_response :success
+    assert_equal Version.current.to_s, JSON.parse(@response.body)["application_version"]
+    assert_equal Apipie.configuration.default_version, JSON.parse(@response.body)["api_version"]
+    assert_equal "oss", JSON.parse(@response.body)["edition"]
+  end
+end

test/test_helper.rb

@@ -22,3 +22,9 @@ class ActiveSupport::TestCase
   fixtures :all
   # Add more helper methods to be used by all tests here...
 end
+
+module ActionDispatch
+  class IntegrationTest
+    include Devise::Test::IntegrationHelpers
+  end
+end