Move API from "api/v2" to "ats-api/v1"

The original API in the service is an API that the public can consume to
get information about the posted vacancies.

The new API is going to be private and only accessible to the ATS so
they can Publish their vacancies into our system.

To avoid confusion, extracted the new API definition under the following
path in our project:

"app/controller/publishers/ats_api/v1/...."

So developers can identify the scope of this API.

To avoid a long convoluted API endpoint for our clients, we will expose
it under "/ats-api/v1" path.

.github/workflows/build_and_deploy.yml

@@ -67,7 +67,7 @@ jobs:
         id: swagger-cache
         with:
           path: 'swagger'
-          key: ${{ runner.os }}-swagger-${{ hashFiles('spec/requests/api/v2/**') }}
+          key: ${{ runner.os }}-swagger-${{ hashFiles('spec/requests/publishers/ats_api/v1/**') }}
 
   build:
     if: contains(github.event.pull_request.labels.*.name, 'deploy') || github.event_name != 'pull_request'
@@ -137,7 +137,7 @@ jobs:
         id: swagger-cache
         with:
           path: 'swagger'
-          key: ${{ runner.os }}-swagger-${{ hashFiles('spec/requests/api/v2/**') }}
+          key: ${{ runner.os }}-swagger-${{ hashFiles('spec/requests/publishers/ats_api/v1/**') }}
           fail-on-cache-miss: true
 
       - name: Build and push docker image from builder target

app/controllers/api/v2/vacancies_controller.rb → app/controllers/publishers/ats_api/v1/vacancies_controller.rb

@@ -1,4 +1,4 @@
-class Api::V2::VacanciesController < Api::ApplicationController
+class Publishers::AtsApi::V1::VacanciesController < Api::ApplicationController
   def index
     @pagy, @vacancies = pagy(vacancies, items: 100)
 

config/initializers/rswag_ui.rb

@@ -7,7 +7,7 @@
   # (under openapi_root) as JSON or YAML endpoints, then the list below should
   # correspond to the relative paths for those endpoints.
 
-  c.openapi_endpoint "/api-docs/v2/swagger.yaml", "API V2 Docs"
+  c.openapi_endpoint "/ats-api-docs/v1/swagger.yaml", "ATS API V1 Docs"
 
   # Add Basic Auth in case your API is private
   # c.basic_auth_enabled = true

config/routes.rb

@@ -2,8 +2,9 @@
 require "sidekiq/cron/web"
 
 Rails.application.routes.draw do
-  mount Rswag::Ui::Engine => "/api-docs"
-  mount Rswag::Api::Engine => "/api-docs"
+  mount Rswag::Ui::Engine => "/ats-api-docs"
+  mount Rswag::Api::Engine => "/ats-api-docs"
+
   if Rails.env.development?
     mount Sidekiq::Web, at: "/sidekiq"
   else
@@ -343,13 +344,16 @@
       get "/organisations", to: "organisations#index", as: :organisations
       resources :markers, only: %i[show]
     end
-    scope "v:api_version", api_version: /2/ do
-      resources :vacancies, only: %i[index show create update destroy], controller: "v2/vacancies", format: :json
-    end
 
     resources :events, only: %i[create]
   end
 
+  namespace :ats_api, path: "ats-api" do
+    scope "v:api_version", api_version: /1/ do
+      resources :vacancies, only: %i[index show create update destroy], controller: "publishers/ats_api/v1/vacancies", format: :json
+    end
+  end
+
   scope "/organisation", as: "organisation" do
     scope constraints: { type: /(published|draft|pending|expired|awaiting_feedback)/ } do
       get "jobs(/:type)", to: "publishers/vacancies#index", defaults: { type: :published }, as: :jobs_with_type

spec/requests/api/v2/vacancies_spec.rb → spec/requests/publishers/ats_api/v1/vacancies_spec.rb

@@ -2,16 +2,16 @@
 
 # rubocop:disable RSpec/EmptyExampleGroup
 # rubocop:disable RSpec/ScatteredSetup
-RSpec.describe "api/v2/vacancies" do
-  path "/api/v{api_version}/vacancies" do
+RSpec.describe "ats-api/v1/vacancies" do
+  path "/ats-api/v{api_version}/vacancies" do
     parameter name: "api_version", in: :path, type: :string, description: "api_version"
 
     get("list vacancies") do
       consumes "application/json"
       produces "application/json"
 
       response(200, "successful") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
         let(:page) { nil }
 
         before do
@@ -366,7 +366,7 @@
       }
 
       response(201, "successful") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
 
         after do |example|
           example.metadata[:response][:content] = {
@@ -394,7 +394,7 @@
       end
 
       response(400, "error") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
 
         after do |example|
           example.metadata[:response][:content] = {
@@ -439,7 +439,7 @@
     end
   end
 
-  path "/api/v{api_version}/vacancies/{id}" do
+  path "/ats-api/v{api_version}/vacancies/{id}" do
     parameter name: "api_version", in: :path, type: :string, description: "api_version"
     parameter name: "id", in: :path, type: :string, description: "id"
 
@@ -450,7 +450,7 @@
       produces "application/json"
 
       response(200, "successful") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
 
         after do |example|
           example.metadata[:response][:content] = {
@@ -529,7 +529,7 @@
       produces "application/json"
 
       response(200, "successful") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
 
         run_test!
       end
@@ -539,7 +539,7 @@
       consumes "application/json"
 
       response(204, "successful") do
-        let(:api_version) { "2" }
+        let(:api_version) { "1" }
 
         run_test!
       end

spec/swagger_helper.rb

@@ -13,11 +13,11 @@
   # document below. You can override this behavior by adding a openapi_spec tag to the
   # the root example_group in your specs, e.g. describe '...', openapi_spec: 'v2/swagger.json'
   config.openapi_specs = {
-    "v2/swagger.yaml" => {
+    "v1/swagger.yaml" => {
       openapi: "3.0.1",
       info: {
-        title: "API V2",
-        version: "v2",
+        title: "Teaching Vacancies ATS API",
+        version: "v1",
       },
       paths: {},
       # servers: [