Merge pull request #224 from braktar/doc-out

Document output
Mapotempo · Aug 13, 2021 · ef3e289 · ef3e289
2 parents b87ec0f + 9434188
commit ef3e289
Show file tree

Hide file tree

Showing 8 changed files with 52 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,8 @@
 - Return route day/date and visits' index in result [#196](https://github.com/Mapotempo/optimizer-api/pull/196)
 - Treat complex shipments (multi-pickup-single-delivery and single-pickup-multi-delivery) as multiple simple shipments internally to increase performance [#261](https://github.com/Mapotempo/optimizer-api/pull/261)
 
+- Document return codes [#224](https://github.com/Mapotempo/optimizer-api/pull/224)
+
 ### Changed
 
 - Improve cases where a service has two visits in periodic heuristic: ensure that the second visit can be assigned to the right day [#227](https://github.com/Mapotempo/optimizer-api/pull/227)

diff --git a/api/v01/api.rb b/api/v01/api.rb
@@ -125,9 +125,9 @@ def count_incr(operation, options)
 
       before do
         if !params || !::OptimizerWrapper.access(true).key?(params[:api_key])
-          error!('401 Unauthorized', 401)
+          error!('Unauthorized', 401)
         elsif OptimizerWrapper.access[params[:api_key]][:expire_at]&.to_date&.send(:<, Date.today)
-          error!('402 Subscription expired', 402)
+          error!("Subscription expired. Please contact support (#{::OptimizerWrapper.config[:product_support_email]}) or sales (#{::OptimizerWrapper.config[:product_sales_email]}) to extend your access period.", 402)
         end
         set_locale
       end

diff --git a/api/v01/entities/vrp_result.rb b/api/v01/entities/vrp_result.rb
@@ -150,6 +150,14 @@ class VrpResult < Grape::Entity
       expose :job, using: VrpResultJob, documentation: { desc: 'The Job status' }
     end
 
+    class VrpSyncJob < Grape::Entity
+      expose :solutions, using: VrpResultSolution, documentation: { is_array: true, desc: 'The current best solution' }
+    end
+
+    class VrpAsyncJob < Grape::Entity
+      expose :job, using: VrpResultJob, documentation: { desc: 'The Job status' }
+    end
+
     class VrpJobsList < Grape::Entity
       expose :jobs, using: VrpResultJob, documentation: { is_array: true, desc: 'The Jobs' }
     end

diff --git a/api/v01/vrp.rb b/api/v01/vrp.rb
@@ -75,10 +75,32 @@ class Vrp < APIBase
           desc 'Submit VRP problem', {
 
             nickname: 'submit_vrp',
-            success: VrpResult,
-            failure: [
-              { code: 400, message: 'Bad Request', model: ::Api::V01::Status }
-            ],
+            success: [{
+              code: 200,
+              message: 'The VRP has been processed synchronously',
+              model: VrpSyncJob
+            }, {
+              code: 201,
+              message: 'The VRP has been placed in a queue to be processed',
+              model: VrpAsyncJob
+            }],
+            failure: [{
+                code: 400,
+                message: 'Bad Request',
+                model: ::Api::V01::Status
+              }, {
+                code: 401,
+                message: 'Unauthorized',
+                model: ::Api::V01::Status
+              }, {
+                code: 402,
+                message: "Subscription expired. Please contact support (#{::OptimizerWrapper.config[:product_support_email]}) or sales (#{::OptimizerWrapper.config[:product_sales_email]}) to extend your access period.",
+                model: ::Api::V01::Status
+              }, {
+                code: 413,
+                message: "Exceeded limit authorized for your account. Please contact support (#{::OptimizerWrapper.config[:product_support_email]}) or sales (#{::OptimizerWrapper.config[:product_sales_email]}) to increase limits.",
+                model: ::Api::V01::Status
+            }],
             detail: 'Submit vehicle routing problem. If the problem can be quickly solved, the solution is returned in the response. In other case, the response provides a job identifier in a queue: you need to perfom another request to fetch vrp job status and solution.'
           }
           params {
@@ -97,7 +119,7 @@ class Vrp < APIBase
               next if vrp_params[key].nil? || value.nil? || vrp_params[key].size <= value
 
               error!({
-                message: "Exceeded #{key} limit authorized for your account: #{value}. Please contact support or sales to increase limits."
+                message: "Exceeded #{key} limit authorized for your account: #{value}. Please contact support (#{::OptimizerWrapper.config[:product_support_email]}) or sales (#{::OptimizerWrapper.config[:product_sales_email]}) to increase limits."
               }, 413)
             }
 
@@ -202,7 +224,10 @@ class Vrp < APIBase
 
           desc 'Delete vrp job', {
             nickname: 'deleteJob',
-            success: { code: 204 },
+            success: {
+              code: 202,
+              model: VrpResult
+            },
             failure: [
               { code: 404, message: 'Not Found', model: ::Api::V01::Status }
             ],

diff --git a/config/environments/development.rb b/config/environments/development.rb
@@ -60,6 +60,8 @@ module OptimizerWrapper
     product_title: 'Optimizers API',
     product_contact_email: 'tech@mapotempo.com',
     product_contact_url: 'https://github.com/Mapotempo/optimizer-api',
+    product_support_email: 'support@mapotempo.com',
+    product_sales_email: 'sales@mapotempo.com',
     access_by_api_key: {
       file: './config/access.rb'
     },

diff --git a/config/environments/production.rb b/config/environments/production.rb
@@ -57,6 +57,8 @@ module OptimizerWrapper
     product_title: 'Optimizers API',
     product_contact_email: 'tech@mapotempo.com',
     product_contact_url: 'https://github.com/Mapotempo/optimizer-api',
+    product_support_email: 'support@mapotempo.com',
+    product_sales_email: 'sales@mapotempo.com',
     access_by_api_key: {
       file: './config/access.rb'
     },

diff --git a/config/environments/test.rb b/config/environments/test.rb
@@ -59,6 +59,8 @@ module OptimizerWrapper
     product_title: 'Optimizers API',
     product_contact_email: 'tech@mapotempo.com',
     product_contact_url: 'https://github.com/Mapotempo/optimizer-api',
+    product_support_email: 'support@mapotempo.com',
+    product_sales_email: 'sales@mapotempo.com',
     access_by_api_key: {
       file: './config/access.rb'
     },

diff --git a/test/api/v01/api_test.rb b/test/api/v01/api_test.rb
@@ -27,12 +27,12 @@ def app
   def test_should_not_access
     get '/0.1/vrp/submit'
     assert_equal 401, last_response.status
-    assert_equal '401 Unauthorized', JSON.parse(last_response.body)['error']
+    assert_equal 'Unauthorized', JSON.parse(last_response.body)['error']
   end
 
   def test_should_not_access_if_expired
     get '/0.1/vrp/submit', api_key: 'expired'
     assert_equal 402, last_response.status
-    assert_equal '402 Subscription expired', JSON.parse(last_response.body)['error']
+    assert_equal 'Subscription expired. Please contact support (support@mapotempo.com) or sales (sales@mapotempo.com) to extend your access period.', JSON.parse(last_response.body)['error']
   end
-end
+end