Add a /entities endpoint to the API #714

.gitignore

@@ -15,3 +15,4 @@ dist/
 /tags
 .tags*
 .noseids
+.pytest_cache

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+### 24.3.0 [#714](https://github.com/openfisca/openfisca-core/pull/714)
+
+- Introduce the `/entities` endpoint for the Web API.
+  - Expose information about the country package's entities, and their roles.
+```json
+{
+            "description": "Household",
+            "documentation": "Household is an example of a group entity. A group entity contains one or more individual·s.[...]",
+            "plural": "households",
+            "roles": {
+                "parent": {
+                    "description": "The one or two adults in charge of the household.",
+                    "max": 2,
+                    "plural": "parents"
+                    },
+                "child": {
+                    "description": "Other individuals living in the household.",
+                    "plural": "children"
+                    }
+                }
+            }
+```
+
 ## 24.2.0 [#712](https://github.com/openfisca/openfisca-core/pull/712)
 
 - Allow to dump and restore a simulation in a directory

openfisca_web_api/app.py

@@ -113,6 +113,10 @@ def get_variable(id):
             raise abort(404)
         return jsonify(variable)
 
+    @app.route('/entities')
+    def get_entities():
+        return jsonify(data['entities'])
+
     @app.route('/spec')
     def get_spec():
         # Ugly Python2-compatible way

openfisca_web_api/loader/__init__.py

@@ -4,6 +4,7 @@
 
 from openfisca_web_api.loader.parameters import build_parameters
 from openfisca_web_api.loader.variables import build_variables
+from openfisca_web_api.loader.entities import build_entities
 from openfisca_web_api.loader.spec import build_openAPI_specification
 
 
@@ -18,5 +19,6 @@ def build_data(tax_benefit_system):
         'openAPI_spec': openAPI_spec,
         'parameters': parameters,
         'variables': variables,
+        'entities': build_entities(tax_benefit_system),
         'host': None  # Will be set by mirroring requests
         }

openfisca_web_api/loader/entities.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals, print_function, division, absolute_import
+from openfisca_core.commons import to_unicode
+
+
+def build_entities(tax_benefit_system):
+    entities = {
+        entity.key: build_entity(entity)
+        for entity in tax_benefit_system.entities
+        }
+    return entities
+
+
+def build_entity(entity):
+    formatted_doc = to_unicode(entity.doc.strip())
+
+    formatted_entity = {
+        'plural': entity.plural,
+        'description': to_unicode(entity.label),
+        'documentation': formatted_doc
+        }
+    if not entity.is_person:
+        formatted_entity['roles'] = {
+            role.key: build_role(role)
+            for role in entity.roles
+            }
+    return formatted_entity
+
+
+def build_role(role):
+    formatted_role = {
+        'plural': role.plural,
+        'description': role.doc
+        }
+
+    if role.max:
+        formatted_role['max'] = role.max
+    if role.subroles:
+        formatted_role['max'] = len(role.subroles)
+
+    return formatted_role

openfisca_web_api/openAPI.yml

@@ -16,13 +16,18 @@ tags:
   - name: "Parameters"
     description: "A parameter is a numeric property of the legislation that can evolve over time."
     externalDocs:
-      description: "Parameter official documentation"
+      description: "Parameters documentation"
       url: "https://openfisca.org/doc/parameters"
   - name: "Variables"
     description: "A variable depends on a person, or an entity (e.g. zip code, salary, income tax)."
     externalDocs:
-      description: "Variable official documentation"
+      description: "Variables documentation"
       url: "https://openfisca.org/doc/variables"
+  - name: "Entities"
+    description: "An entity is a person of a group of individuals (such as a household)."
+    externalDocs:
+      description: "Entities documentation"
+      url: "https://openfisca.org/doc/person,_entities,_role.html"
   - name: "Calculations"
   - name: "Documentation"
 paths:
@@ -138,6 +143,21 @@ paths:
           description: "The requested variable does not exist"
           headers:
             $ref: '#/commons/Headers'
+  /entities:
+    get:
+      tags:
+      - "Entities"
+      summary: "List all available Entities"
+      operationId: "getVariables"
+      produces:
+      - "application/json"
+      responses:
+        200:
+          description: "The list of the entities as well as their information is sent back in the response body"
+          headers:
+            $ref: '#/commons/Headers'
+          schema:
+            $ref: "#/definitions/Entities"
   /trace:
     post:
       summary: "Explore a simulation's steps in details."
@@ -318,6 +338,28 @@ definitions:
       type: "number"
       format: "float"
 
+  Entities:
+    type: "object"
+    properties:
+      description:
+        type: "string"
+      documentation:
+        type: "string"
+      plural:
+        type: "string"
+      roles:
+        type: "object"
+        additionalProperties:
+         $ref: "#/definitions/Roles"
+  Roles:
+    type: "object"
+    properties:
+      description:
+        type: "string"
+      max:
+        type: "integer"
+      plural:
+        type: "string"
   SituationInput:
     example:
       individus:

setup.py

@@ -31,7 +31,7 @@
 
 setup(
     name = 'OpenFisca-Core',
-    version = '24.2.0',
+    version = '24.3.0',
     author = 'OpenFisca Team',
     author_email = 'contact@openfisca.org',
     classifiers = [

tests/web_api/test_entities.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals, print_function, division, absolute_import
+from http.client import OK
+from nose.tools import assert_equal
+import json
+import openfisca_country_template
+from openfisca_core.commons import to_unicode
+from . import subject
+
+entities_response = subject.get('/entities')
+
+# /entities
+
+
+def test_return_code():
+    assert_equal(entities_response.status_code, OK)
+
+
+def test_response_data():
+    entities = json.loads(entities_response.data.decode('utf-8'))
+    test_documentation = to_unicode(openfisca_country_template.entities.Household.doc.strip())
+
+    assert_equal(
+        entities['household'],
+        {
+            'description': 'Household',
+            'documentation': test_documentation,
+            'plural': 'households',
+            'roles': {
+                'child': {
+                    'description': 'Other individuals living in the household.',
+                    'plural': 'children'
+                    },
+                'parent': {
+                    'description': 'The one or two adults in charge of the household.',
+                    'max': 2,
+                    'plural': "parents"
+                    }
+                }
+            }
+        )

tests/web_api/test_spec.py

@@ -31,6 +31,7 @@ def test_paths():
         "/parameters",
         "/variable/{variableID}",
         "/variables",
+        "/entities",
         "/trace",
         "/calculate",
         "/spec"]