Openfisca-core

Breaking changes

Only install the Web API dependencies as an opt-in:

- `pip install OpenFisca-Core` will _not_ install the Web API anymore.
- `pip install OpenFisca-Core[web-api]` will.

Country package maintainers who still want to provide the Web API by default with their package (**recommended**) should update their `setup.py`:
- In the `install_requires` section, replace `'OpenFisca-Core >= 23.3, < 24.0'` by `'OpenFisca-Core[api] >= 24.0, < 25.0'`
- See [example](https://github.com/openfisca/country-template/commit/b75eea97d8d22091a3f13a580118ce45b16f4294)

Change default Web API port to 5000:

- `openfisca serve` will now serve by default on the `5000` port instead of `6000` (blocked by Chrome).

Rename OpenFisca Web Api package to `openfisca_web_api`:

- Transparent for users of the `openfisca serve` command.
- Users who used to manually import `openfisca_web_api_preview` must know import `openfisca_web_api`.

Rename development dependencies from `test` to `dev`:

- Developpers should now run `pip install --editable .[dev]` instead of `pip install --editable .[test]` to install them.

New features

- In the `/spec` route:
- Indicate the served country package version as API version (instead of `0.1.0`).
- Infer the host URL from the requests, instead of relying on the undocumented `SERVER_NAME` environnement variable.
- The use of the `SERVER_NAME` environnement variable is therefore deprecated and without effect.

- Revert the undesired side effects of `23.4.0` on the `parameters/` overview route of the Web API
- This route now behaves the exact same way than before `23.4.0`
- The keys of the `/parameters` JSON object are back to using the `.` notation
- Parameter nodes are for now not exposed in the `parameters/` overview (but each of them is exposed in `/parameter/path/to/node`)

_Note: this version has been unpublished due to an issue introduced by 23.4.0 in the Web API. Please use 23.5.2 or a more recent version._

- Remove the irrelevant decimals that were added at the end of `float` results in the Web API and the test runner.
- These decimals were added while converting a NumPy `float32` to a regular 64-bits Python `float`.

For instance, the former Web API response extract:

json
"tax_incentive": {
"2017-01": 333.3333435058594
}


becomes:

json
"tax_incentive": {
"2017-01": 333.33334
}

_Note: this version has been unpublished due to an issue introduced by 23.4.0 in the Web API. Please use 23.5.2 or a more recent version._

* 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))

_Note: this version has been unpublished due to an issue introduced by 23.4.0 in the Web API. Please use 23.5.2 or a more recent version._

* Fix API source IP detection through proxies.

_Note: this version has been unpublished as it introduced an issue in the Web API. Please use 23.5.2 or a more recent version._

* Use `/` rather than `.` in the path to access a parameter:
- For instance `/parameter/benefits.basic_income` becomes `/parameter/benefits/basic_income`
- Using `.` is for now still supported, but is considered deprecated and will be turned to a 301 redirection in the next major version.

* Expose parameters `metadata` and `source` in the Web API and:

For instance, `/parameter/benefits/basic_income` contains:

JSON
{
"description": "Amount of the basic income",
"id": "benefits.basic_income",
"metadata": {
"reference": "https://law.gov.example/basic-income/amount",
"unit": "currency-EUR"
},
"source": "https://github.com/openfisca/country-template/blob/3.2.2/openfisca_country_template/parameters/benefits/basic_income.yaml",
"values": {
"2015-12-01": 600.0
}
}


* Expose parameters nodes in the Web API
- For instance, `/parameter/benefits` now exists and contains:

JSON
{
"description": "Social benefits",
"id": "benefits",
"metadata": {},
"source": "https://github.com/openfisca/country-template/blob/3.2.2/openfisca_country_template/parameters/benefits",
"subparams": {
"basic_income": {
"description": "Amount of the basic income"
},
"housing_allowance": {
"description": "Housing allowance amount (as a fraction of the rent)"
}
}
}


Note that this route doesn't _recursively_ explore the node, and only exposes its direct children name and description.