Design new calculate endpoint

[cbenz]

Create a new endpoint merging existing calculate and simulate endpoint. This would be the version 2 of calculate so let's name it /api/2/calculate.

Here are some constraints:

• the Web API must remain stateless (no session on the server)
• the JSON payload brings the calculate request

  Input

The new endpoint should be able to accept multiple formats in input:

• test case
• arrays

Options

• simple_test_case: allow a test case to be incomplete

  Output

The output format should be either:

• test case
• arrays

Some feature are already provided by calculate or simulate. The aim of the new endpoint is to unify them in a consistent manner.

Examples

TODO

[cbenz]

I'd like to get rid of the Google JSON Style Guide keys in the output JSON like apiVersion, context and params. I mean that the client should be able to remember the context of the API call, and I'm pretty sure that relying on the API response is not a good idea.

[cbenz]

I'd like to redesign the reforms and base_reforms keys of the JSON payload, to replace it with a unique extensions key:

• default value is "extensions": null: 1 simulation is done with no extension loaded
• value can be a string "extensions": "extension1: 1 simulation is done with the specified extension loaded
• value can be an array of strings "extensions": ["extension1", "extension2"]: 1 simulation is done with the specified extensions loaded and chained

• value can be an array of {null, <string>, <array>}

  {
    "extensions": [
         null,
        "extension1",
         ["extension1", "extension2"]
    ]
  }

  many simulations are done, each with the specified extensions loaded

[cbenz]

The "output_format" key should be related to each scenario, not to the payload.

[cbenz]

Allow entities of "test_case" to be objects indexed by the entity "id", since there is no order to be declared.

Example:

{
  "scenarios": [
    {
      "test_case": {
-        "familles": [
-          {
-            "id": "famille_0",
-            "parents": ["individu0"]
-          }
-        ],
+        "familles": {
+          "famille_0": {
+            "parents": ["individu_0"]
+          }
+        },
        "foyers_fiscaux": {
          "foyer_fiscal_0": {
            "declarants": ["individu_0"]
          }
        },
        "individus": {
          "individu_0": {
            "birth": "1980-01-01"
          }
        },
        "menages": {
          "menage_0": {
            "personne_de_reference": "individu_0"
          }
        }
      },
      "period": "2015"
    }
  ],
  "variables": ["revdisp"]
}

CC @MattiSG Still interested in this feature?

[MattiSG]

The design of a new endpoint to supersede existing endpoints will be iterative. There won't be a single issue to design it all at once. These design elements will be very useful reference to keep in mind, but the age of this issue shows that waterfall delivery won't work.