Make API discoverable from the root

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 23.5.0 [#705](https://github.com/openfisca/openfisca-core/pull/705)
+
+* On the Web API, expose a welcome message (with a 300 code) on `/` instead of a 404 error.
+
+For instance, `curl -i localhost:5000` gives:
+
+```
+HTTP/1.1 300 MULTIPLE CHOICES
+(...)
+
+{
+  "welcome": "This is the root of an OpenFisca Web API. To learn how to use it, check the general documentation (https://openfisca.org/doc/api) and the OpenAPI specification of this instance (http://localhost:5000/spec)."
+}
+```
+
+* This message can be customized:
+
+If the Web API is started with `openfisca serve -p 3000 --welcome-message "Welcome to the OpenFisca-France Web API. To learn how to use it, check our interactive swagger documentation: https://fr.openfisca.org/legislation/swagger."`
+
+Then `curl -i localhost:5000` gives:
+
+```
+HTTP/1.1 300 MULTIPLE CHOICES
+(...)
+
+{
+  "welcome": "Welcome to the OpenFisca-France Web API. To learn how to use it, check our interactive swagger documenation: https://fr.openfisca.org/legislation/swagger"
+}
+```
+
+(Like other configuration variables, this custom message can also be defined in a configuration file. Check the [openfisca serve documentation](https://openfisca.readthedocs.io/en/latest/openfisca_serve.html))
+
+
 ### 23.4.1 [#700](https://github.com/openfisca/openfisca-core/pull/700)
 
 * Fix API source IP detection through proxies.

openfisca_web_api_preview/app.py

@@ -41,7 +41,8 @@ def init_tracker(url, idsite, tracker_token):
 def create_app(tax_benefit_system,
                tracker_url = None,
                tracker_idsite = None,
-               tracker_token = None
+               tracker_token = None,
+               welcome_message = None,
                ):
 
     if not tracker_url or not tracker_idsite:
@@ -58,6 +59,14 @@ def create_app(tax_benefit_system,
 
     data = build_data(tax_benefit_system)
 
+    DEFAULT_WELCOME_MESSAGE = "This is the root of an OpenFisca Web API. To learn how to use it, check the general documentation (https://openfisca.org/doc/api) and the OpenAPI specification of this instance ({}spec)."
+
+    @app.route('/')
+    def get_root():
+        return jsonify({
+            'welcome': welcome_message or DEFAULT_WELCOME_MESSAGE.format(request.host_url)
+            }), 300
+
     @app.route('/parameters')
     def get_parameters():
         return jsonify(data['parameters_description'])
@@ -86,7 +95,15 @@ def get_variable(id):
 
     @app.route('/spec')
     def get_spec():
-        return jsonify(data['openAPI_spec'])
+
+        # Ugly Python2-compatible way
+        response = {}
+        response.update(data['openAPI_spec'])
+        response.update({'host': request.host_url})
+        return jsonify(response)
+
+        # Nice Python3 syntax, but doesn't work in Python 2
+        # return jsonify({**data['openAPI_spec'], **{'host': request.host_url}})
 
     def handle_invalid_json(error):
         json_response = jsonify({

openfisca_web_api_preview/loader/__init__.py

@@ -26,4 +26,5 @@ def build_data(tax_benefit_system):
         'parameters_description': extract_description(parameters),
         'variables': variables,
         'variables_description': extract_description(variables),
+        'host': None  # Will be set by mirroring requests
         }

openfisca_web_api_preview/loader/spec.py

@@ -16,7 +16,6 @@ def build_openAPI_specification(tax_benefit_system, country_package_metadata):
     country_package_name = country_package_metadata['name'].title()
     spec['info']['title'] = spec['info']['title'].replace("{COUNTRY_PACKAGE_NAME}", country_package_name)
     spec['info']['description'] = spec['info']['description'].replace("{COUNTRY_PACKAGE_NAME}", country_package_name)
-    spec['host'] = os.environ.get('SERVER_NAME')
 
     for entity in tax_benefit_system.entities:
         name = entity.key.title()

openfisca_web_api_preview/scripts/serve.py

@@ -34,6 +34,7 @@ def define_command_line_options(parser):
     parser.add_argument('--tracker-url', action = 'store', help = "tracking service url", type = str)
     parser.add_argument('--tracker-idsite', action = 'store', help = "tracking service id site", type = int)
     parser.add_argument('--tracker-token', action = 'store', help = "tracking service authentication token", type = str)
+    parser.add_argument('--welcome-message', action = 'store', help = "welcome message users will get when visiting the API root", type = str)
     parser.add_argument('-f', '--configuration-file', action = 'store', help = "configuration file", type = str)
 
     return parser
@@ -92,7 +93,9 @@ def load(self):
         return create_app(
             tax_benefit_system,
             self.options.get('tracker_url'),
-            self.options.get('tracker_idsite')
+            self.options.get('tracker_idsite'),
+            self.options.get('tracker_token'),
+            self.options.get('welcome_message')
             )
 
 

setup.py

@@ -8,11 +8,11 @@
 
 setup(
     name = 'OpenFisca-Core',
-    version = '23.4.1',
+    version = '23.5.0',
     author = 'OpenFisca Team',
-    author_email = 'contact@openfisca.fr',
+    author_email = 'contact@openfisca.org',
     classifiers = [
-        "Development Status :: 2 - Pre-Alpha",
+        "Development Status :: 5 - Production/Stable",
         "License :: OSI Approved :: GNU Affero General Public License v3",
         "Operating System :: POSIX",
         "Programming Language :: Python",
@@ -46,7 +46,7 @@
         'dpath == 1.4.0',
         'enum34 >= 1.1.6',
         'future',
-        'flask == 0.12',
+        'flask == 1.0.2',
         'flask-cors == 3.0.2',
         'gunicorn >= 19.7.1',
         'numpy >= 1.11, < 1.15',