Merge pull request #303 from openfisca/webapi

Improve copywriting for Web API

source/openfisca-web-api/config-openapi.md

@@ -2,17 +2,17 @@
 
 The OpenFisca web API exposes a `/spec` route that documents how to use the API, using the OpenAPI standard.
 
-Most the the `/spec` content is automatically built for you. However, some minimal configuration can make the provided examples more complete and relevant, and improve the [Swagger interactive documentation packaged in the Legislation Explorer](http://demo.openfisca.org/legislation/swagger).
+Most of the `/spec` content is automatically built for you. However, some minimal configuration can make the provided examples more complete and relevant, and improve the [Swagger interactive documentation packaged in the Legislation Explorer](http://demo.openfisca.org/legislation/swagger).
 
 This configuration is done in the initialisation of your `TaxBenefitSystem`. For example, in the [country package template](https://github.com/openfisca/country-template/blob/3.5.0/openfisca_country_template/__init__.py#L28-L33), you can see:
 
 ```py
   # We define which variable, parameter and simulation example will be used in the OpenAPI specification
   self.open_api_config = {
-    "variable_example": "disposable_income",
-    "parameter_example": "taxes.income_tax_rate",
-    "simulation_example": couple,
-    }
+      "variable_example": "disposable_income",
+      "parameter_example": "taxes.income_tax_rate",
+      "simulation_example": couple,
+      }
 ```
 
 This defines:

source/openfisca-web-api/endpoints.md

@@ -1,7 +1,7 @@
-# Endpoints
+# API endpoints
 
 Each OpenFisca Country Package web API comes with a set of endpoints including an OpenAPI specification on the `/spec` route.
-You can check out the demonstration [swagger documentation](http://demo.openfisca.org/legislation/swagger) to see how the endpoints work.
+You can check out the demonstration [swagger documentation](https://legislation.demo.openfisca.org/swagger) to see how the endpoints work.
 
 The OpenFisca web API can be used to:
 

source/openfisca-web-api/index.md

@@ -12,23 +12,24 @@ config-openapi
 OpenFisca provides a web API package, compatible with all country packages.
 Using a web interface, app developers can access information and computations without installing anything locally.
 
-## Public France API
+## Demonstration API
 
-The latest version of the France web API is [`api.fr.openfisca.org/latest`](https://api.fr.openfisca.org/latest). Its endpoints are documented in [`fr.openfisca.org/legislation/swagger`](https://fr.openfisca.org/legislation/swagger). This API is provided for prototyping purposes only: it has no SLA (service level agreement, i.e. guarantee of availability) and is kept up to date automatically, with no regard for breaking changes. No support will be provided for this instance. You should not build production systems on top of it.
+The latest version of the OpenFisca Country Template web API can be found at [`api.demo.openfisca.org`](https://api.demo.openfisca.org/). Its endpoints are documented at [`legislation.demo.openfisca.org/swagger`](https://legislation.demo.openfisca.org/swagger).
 
-Anyone wanting a stable OpenFisca web API is invited to [host their own](#hosting-an-api-instance).
+## OpenFisca country APIs
+
+Each country/jurisdiction can host an API endpoint and often an OpenFisca instance is deployed multiple times in support of different applications.
+By way of example, an instance of the French API is available at [api.fr.openfisca.org](https://api.fr.openfisca.org/). It is provided for prototyping purposes only: it has no SLA (service level agreement, i.e. guarantee of availability) and is kept up to date automatically, with no regard for breaking changes. No support is provided for this instance. You should not build production systems against it.
 
-## Use Cases
+Anyone wanting a stable OpenFisca web API is invited to [host their own](#hosting-an-api-instance).
 
-The following services use the OpenFisca web API:
+## Example use cases
 
-- [fr.openfisca.org/legislation](https://fr.openfisca.org/legislation), giving you information on available OpenFisca variables.
-- [Mes Aides](https://mes-aides.gouv.fr), the French social benefits simulator.
-- [PA-comp](https://pa-comp.firebaseapp.com), a divorce fiscal impact simulator.
+Visit [https://openfisca.org/en/showcase/](https://openfisca.org/en/showcase/) to browse a wide variety of use cases.
 
 ## Conditions
 
-Please remember that OpenFisca is free software, licensed under an [Affero GPL license](https://choosealicense.com/licenses/agpl-3.0/). That means you have to provide access to the source code of the API you make available, including any changes you might have made on the original code. You also have to provide a link to the OpenFisca source code, and state its license, in a place that is easily discoverable by users of your software.
+Please remember that OpenFisca is free software, licensed under an [Affero GPL licence](https://choosealicense.com/licenses/agpl-3.0/). That means you have to provide access to the source code of the API you make available, including any changes you might have made to the original code. You also have to provide a link to the OpenFisca source code, and state its licence, in a place that is easily discoverable by users of your software.
 
 You could for example add one the following lines to a “credits” page:
 

source/openfisca-web-api/input-output-data.md

@@ -2,19 +2,19 @@
 
 > All the examples provided here are from the [country package template](https://github.com/openfisca/country-template).
 
-In order to run a computation on the web API, you will need to send information to the API concerning:
+In order to run a computation on the web API, you need to send the following information to the API in the JSON format:
 
-- The situation, meaning describe the [entities](../key-concepts/person,_entities,_role.md) (e.g. individuals, households) that you want to base your calculations on.
+- The situation that describes the [entities](../key-concepts/person,_entities,_role.md) (e.g. individuals, households) that you want to base your calculations on.
 - The variable you need to compute.
 
 ## Describing the situation
 
 ### Describing entities
 
-The most important rule in describing a situation in OpenFisca is:
+When describing situations to OpenFisca, follow these two rules:
 
-Every person has to belong to one of each group entity (e.g. household).
-Every person in a group entity needs a role (e.g. parent)
+ 1. Every person has to belong to one of each group entity (e.g. household).
+ 2. Every person in a group entity needs a role (e.g. parent)
 
 > For example, if you wish to run a calculation on 2 households:
 >
@@ -49,15 +49,15 @@ Every person in a group entity needs a role (e.g. parent)
 
 ### Adding information to entities
 
-To run a precise calculation, you can provide information on each person and group entity.
+To run a precise calculation, you should provide information on each person and group entity.
 
 These are the input [variables](../key-concepts/variables.md) of your simulation.
 
-To provide an input variable, insert the value in the json, for the corresponding time period (e.g. '2015-06') and entity (e.g. 'person', 'household').
+To provide an input variable, insert the value in the json, for the corresponding time period (e.g. `2015-06`) and entity (e.g. `person`, `household`).
 
 The time period must respect the [definition period](../coding-the-legislation/35_periods.md) of the variable, and the entity must be the one the variable is defined for.
 
-> For example, if Ricarda has a salary (defined monthly for a Person) of 3500/month until september 2016, and 4000/month after that and if household_2 were tenant and became homeowners in march 2016 (housing_occupancy_status is defined monthly for a household) of the 57 sqm apartment they live in, you would write:
+> For example, if Ricarda has a salary (defined monthly for a Person) of 3500/month until september 2016, and 4000/month after that and if `household_2` were tenants and became homeowners in March 2016 (`housing_occupancy_status` is defined monthly for a household) of the 57 sqm apartment they live in, you would write:
 
 ```json
 {
@@ -215,7 +215,7 @@ To indicate you want a variable computed, insert the variable in the correspondi
 
 ## Understanding the result
 
-The API will return an identical JSON file where all the `null` (the variable that you asked OpenFisca to compute, see above for details) have been replace by the computed value.
+The API will return an identical JSON file where all the `null` values (the variables that you asked OpenFisca to compute) have been replaced with their computed values.
 
 ```json
 {
@@ -293,4 +293,4 @@ The API will return an identical JSON file where all the `null` (the variable th
 }
 ```
 
-> Note that elements might appear in a different order in the response. However the structure of the file stays the same.
+> Note that elements might appear in a different order in the response. However the structure of the JSON stays the same.

source/openfisca-web-api/trace-simulation.md

@@ -2,11 +2,11 @@
 
 > All the examples provided here are from the [country package template](https://github.com/openfisca/country-template).
 
-When you [run a simulation](input-output-data.md) on a specific situation (e.g. use the `/calculate` endpoint), you might want to understand the calculation. The `/trace` endpoint is here to help you analyse the simulation calculation step by step.
+When [running a simulation](input-output-data.md) on a specific situation (e.g. using the `/calculate` endpoint), you might want to understand the calculation. The `/trace` endpoint is here to help analyse the simulation calculation step by step.
 
 ## Application: analyse disposable income calculation for one person
 
-Let's say that you want to calculate the `disposable_income` for one person earning a `salary` on the same period. You start with the following JSON situation description:
+Let's say that you want to calculate the `disposable_income` for one person earning a `salary` in a specific period. You start with the following JSON situation description:
 
 ```json
 {
@@ -31,7 +31,7 @@ Let's say that you want to calculate the `disposable_income` for one person earn
 }
 ```
 
-If you send this situation to your `country-template` model web API or try it out on the `/trace` endpoint in the [Swagger interface](https://legislation.demo.openfisca.org/swagger), you get the following response composed of three sections:
+If this situation to is sent to the `country-template` model web API or the `/trace` endpoint in the [Swagger interface](https://demo.openfisca.org/legislation/swagger), it will return the following response composed of three sections:
 
 * `entitiesDescription`: lists the persons and how they belong to the model group entities,
 * `requestedCalculations`: lists the requested calculations (i.e. variables with values at `null`),
@@ -147,11 +147,11 @@ It contains these sub-sections:
 * `dependencies`: the [variables](../key-concepts/variables.md) called by `disposable_income` formula and their calculation periods,
 * `parameters`: the [parameters](../key-concepts/parameters.md) called by `disposable_income` formula and their periods.
 
-You can see those variables and parameters in [disposable_income definition](https://legislation.demo.openfisca.org/disposable_income).
+These variables and parameters are visible in the [`disposable_income` definition](https://legislation.demo.openfisca.org/disposable_income).
 
-Following `dependencies` list, we can also see that:
+Following the full `dependencies` list, we can see that:
 
-* OpenFisca didn't need to calculate the `salary` value as it was given in situation inputs; thus the `/trace` doesn't evaluate its `dependencies` and `parameters`:
+* OpenFisca didn't need to calculate the `salary` value as it was supplied in situation inputs; thus the `/trace` doesn't evaluate its `dependencies` and `parameters`:
 
     ```json
     {
@@ -165,7 +165,7 @@ Following `dependencies` list, we can also see that:
     }
     ```
 
-* OpenFisca needed to calculate the next variable, `basic_income`, before `disposable_income` evaluation:
+* OpenFisca needed to calculate the next variable, `basic_income`, before `disposable_income` was calculated:
 
     ```json
     {
@@ -184,8 +184,8 @@ Following `dependencies` list, we can also see that:
     }
     ```
 
-    Note that, as a parameter depends only on its validity period, its evaluation is described in one line that includes its value.
+> Note: as a parameter depends only on its validity period, its period and value are described in one line.
 
-So, with `/trace` endpoint, you can follow calculation steps by following the variable names and periods in its response `trace` section.
+With the `/trace` endpoint, you can trace the calculation steps by following the variable names and periods in its response `trace` section.
 
-> Try it out on the [Swagger interface](https://legislation.demo.openfisca.org/swagger) of `country-template` model.
+> Try it out on the [Swagger interface](https://legislation.demo.openfisca.org/swagger) of the `country-template` model.