ban-archive/api-gestion-poc

POC pour une API de gestion BAN

api-gestion-poc's Issues

Fix districts repr in housenumber resource

{
    "cea": "", 
    "cia": "90001_900010008__18_", 
    "districts": "<class 'ban.core.models.District'> SELECT \"t1\".\"id\", \"t1\".\"version\", \"t1\".\"created_at\", \"t1\".\"created_by_id\", \"t1\".\"modified_at\", \"t1\".\"modified_by_id\", \"t1\".\"name\", \"t1\".\"alias\", \"t1\".\"attributes\", \"t1\".\"municipality_id\" FROM \"district\" AS t1 INNER JOIN \"housenumber_district_through\" AS t2 ON (\"t1\".\"id\" = \"t2\".\"district_id\") INNER JOIN \"housenumber\" AS t3 ON (\"t2\".\"housenumber_id\" = \"t3\".\"id\") WHERE (\"t2\".\"housenumber_id\" = %s) [1]", 
    "id": 1, 
    "number": "18", 
    "ordinal": "", 
    "street": {
        "alias": null, 
        "fantoir": "900010008", 
        "id": 2, 
        "municipality": 21, 
        "name": "Rue de Danjoutin", 
        "version": 1
    }, 
    "version": 1
}

User password

See coleifer/peewee#766

Expose default position in housenumber resource

Valeurs non attendus sur la réponse de requête sur les rues

Sur l'API, lors d'une requête "http://'host':'port'/municipality/14" par exemple, la réponse est de type :
{
"version": 1,
"insee": "33001",
"postcodes": [
"33230"
],
"name": "Abzac",
"id": 14,
"alias": null,
"siren": "213300015"
}

Cependant, en remontant dans la hiérarchie avec : "http://'host':'port'/street/1" on obtient:
{
"version": 1,
"fantoir": "330010005",
"name": "Rue des Arnauds",
"id": 1,
"alias": null,
"municipality": {
"insee": "33001",
"postcodes": "<class 'ban.core.models.PostCode'> SELECT "t1"."id", "t1"."version", "t1"."created_at", "t1"."created_by_id", "t1"."modified_at", "t1"."modified_by_id", "t1"."code" FROM "postcode" AS t1 INNER JOIN "municipality_postcode_through" AS t2 ON ("t1"."id" = "t2"."postcode_id") INNER JOIN "municipality" AS t3 ON ("t2"."municipality_id" = "t3"."id") WHERE ("t2"."municipality_id" = %s) [14]",
"name": "Abzac",
"id": 14,
"alias": null,
"siren": "213300015"
}
}

postcode not exposed in resource housenumber

Link header pagination

https://developer.github.com/v3/#pagination

Cas des adresses de voies ayant plusieurs code postaux

C'est un des retours de l'OpenLab: les utilisateurs cherchent "hexacle" et ne connaissent apparemment pas "cea".

Note: on peut aussi en profiter pour avoir un nom moins cryptique, et renommer en "laposte_id" par exemple, et compter sur la documentation pour rendre ça clair à ceux qui cherchent "hexacle".

cc @Apside-bdx-BBO @christopheprudent

Support If-Modified-Since header

old insee

Que fait-on des anciens codes insee?
En effet, nous avons dans nos fichiers "hexa" l'information sur l'ancien code insee d'une commune ou municipalité.
Est-il nécessaire de renseigner une autre colonne?
Est-ce une information : superflue mais qui peut servir ?

Add diff_id to diff exports

So diff consumers can runs twice the same diff set without reapplying already applied ones.

CRUD information

Actuellement, pour ajouter une entité ET la modifier on utilise un POST.
La formation d'une API RestFul voudrait que le POST soit non-idempotent et que le PUT soit idempotent.
Est-il envisageable que l'on ne vérifie pas la présence d'une entité (par son id) dans la BDD lors un POST; et que l'on ne teste que son nom? Ainsi lors d'un POST on serait en mesure de n'ajouter que de nouvelles entités.

Le PUT servirait à modifier une entité et, en effet, le numéro de version garantirait son idempotence lors de la requête.

De plus, la requete : 'host':'port'/municipality/insee:85000 serait plus de la forme 'host':'port'/municipality/insee/85000 en RestFul.

Expose PostCode in the API

Allow to update zipcodes when editing municipalities from the API

ZipCodes are m2m, so we'll need to work a bit around the validator.

Add bbox filtering for position and housenumber

Do not expose "version" in resource as relation

Useless data.

i18n management

Municipality split

Sometimes, a municipality split in two municipalities. We need to handle that with a command line.

Allow auth.Client creation from the API

Implement a cursor pagination

See http://use-the-index-luke.com/no-offset

Allow to ask diffs from some increment

Add documentation endpoint and return it as 404 body

A json listing:

• contact email
• licence info
• list of endpoints and doc for each

Add DELETE endpoints

Add caching for GET requests

We'll need caching the READ API. This can be Nginx or Squid, or an internal mecanism that would store in Redis for example.

As usual, the hard part will be invalidation. Also, in case not all GET requests are open (and thus some would need a token), we'll need to handle token validity.

Support If-Match header

named URL router

We want a named URL router so we can have a DRYer and more efficient way for reversing URLs.

Swagger?

http://swagger.io/specification/

Not sure it's worth it (high implementation / maintenance cost, real usage to be proven), but let's keep it in the radar.

Principe de composition des id

Bonjour,

Tous les objets du MCD sont identifiés par :

• leur id
• leur version

L'id qui aura le rôle d'identifiant unique sera-t-il un "bête" incrément (style sequence postgreSQL) ou qqch de plus normé à l'instar des uuid, cf https://fr.wikipedia.org/wiki/Universal_Unique_Identifier) ?

Manage scopes

In a first step, we want scopes for:

• municipality write access
• street write access
• housenumber write access
• position write access

Those needs to be set on the client.

References:

• https://www.brandur.org/oauth-scope

• Ajouter un db.ArrayField

• modifier Client.default_scope pour l'écrire en db

• modifier Token.scope en Token.scopes et supprimer la property dynamique

• dans Token.create_from_session, récupérer les scopes du client pour les passer au token

• ajouter la définition des scopes dans auth:createclient

• ajouter dynamiquement les scopes aux endpoints de l'API

• ajouter les scopes dans l'affichage de auth:listclients

Redirect commands reports to /dev/null when running tests without verbosity

Municipality merge

Sometime, two municipality merge, we need to handle that with a command line.

Use peewee.ManyToManyField for ZipCode

Missed that:
http://docs.peewee-orm.com/en/latest/peewee/playhouse.html?highlight=password#ManyToManyField

Suppression d’adresses

A faire via l'API.
Utile pour supprimer des anomalies dans la base ou des doublons montés par erreur.

Exports

We need to export open data, in various format (csv, sjson…), for various areas (France, départements…), and with various flavours (default, postal, which gives priority to postal positions, aid, which gives priority to aid positions, etc.).

Use PostGIS geographic field for Position.center field

Store metadata classes in the MCD

An idea in the BAN MCD: create metadata classes, as it is important, containing versions, sources, dates and linked to different existing classes: HouseNumber and Position.
What about the "lieux-dits"? A zone as well contained in Locality and having an Adress?
From that, I suggest to rename HouseNumber to Adress since a "lieux-dits" can have an adress, not only a house....

Implement PATCH endpoints

Add alias_names for NamedModel

Make sure collection links query string keys are always in the same order

Better for caching, and testing:

  {'next': 'http://falconframework.org/housenumber?east=2&offset=5&west=0&north=2&limit=5&south=0'} != {'next': 'http://falconframework.org/housenumber?offset=5&east=2&limit=5&west=0&north=2&south=0'}

Liste de valeurs admises pour "Position.kind"

On a parlé d'utiliser la terminologie INSPIRE: http://inspire.ec.europa.eu/documents/Data_Specifications/INSPIRE_DataSpecification_AD_v3.1.pdf

Keep identifiers history

I'd go for a simple "identifier_redirect" table.

Ajouter les IRIS?

Citation de #43 :

L'INSEE ne les maintient pas car refuse actuellement (presque ?) tous les redécoupages nécessaires pour tenir compte des évolutions urbaines. Dans plusieurs métropoles nous avons des cas de zones IRIS coupant des immeubles récents ou agrégeant trop de population / logements par rapport à ce que cela devrait être.
Si nous disposions d'un autre maillage infra communal (carreaux 200m ? mais ils bougent) une bonne part des CT l'utiliseraient déjà. Je déconseille déjà utilisation IRIS pour toute analyse sur notre territoire : trop grand et pas à jour (cf http://geobretagne.fr/geonetwork/apps/georchestra/?uuid=df789a3f-9980-4629-95be-50a8b04eac3c)

Consider using rapidjson

python-rapidjson

See also http://blog.ionelmc.ro/2015/11/22/memory-use-and-speed-of-json-parsers/

Langue de la documentation et des tickets

Bonjour,

Il a été remarqué que l'amorce de documentation (qui ne porte à ce jour que sur le MCD) et une bonne partie des échanges via les tickets (issues) est en langue anglaise.

Si cela est quasiment incontournable quand on travaille sur des projets internationaux, on ne cerne pas la nécessité de cela dans le cadre de la BAN qui est un projet franco-français.
Le CNIG, par exemple, a assez clairement défini sa politique en la matière dans le cadre des travaux autour de INSPIRE : pas de traduction systématique des documents en anglais émanant de la Commission Européenne (distorsion des concepts). En revanche, toute la production doit être réalisée en langue française.

Cette remarque n’est pas faite par idéologie ou difficultés de compréhension mais parce que cela peut être considéré comme un frein pour la transparence de la démarche du projet et sa compréhension.
Que le code soit rédigé avec des commentaires de code en anglais n'est pas le sujet. Idem pour le nommage des classes / objets sur le MCD.

Merci d'avance d'apporter des éclaircissements / une ligne directrice.

version should NOT be required on create

Add Location header on object create

[MCD] Fusionner Locality et Street ?

Discussion à lier à #15 #14 et #42

Actuellement, la traduction qui a été donnée de "Locality" est "lieu-dit".
Mais d'après ce qu'on en a compris, cette classe est censée regrouper :

1. les “vrais” lieux-dits avec adresses et/ou les zones d’agrégation d’adresses (ex : zone industrielle)
2. les lieux-dits sans adresses

Cela peut constituer un mécanisme de compensation intéressant dans les territoires où les communes ne se sont pas encore organisées pour la gestion de bases voies-adresses. Comme la BAN ne gère pas la géométrie des voies, cela nous permet de remonter dans cette classe l’existence (et la dénomination officielle) de lieux-dits sans adresses.

A relire la spécification de données INSPIRE, j'ai l'impression que ce concept est très proche du concept de AdressAreaName :

An address component which represents the name of a geographic area or locality that groups a number of addressable objects for addressing purposes, without being an administrative unit.

NOTE 1 In some countries and regions an address area is a true subdivision of an administrative unit (most often a municipality), so that every address area is fully inside the municipality and so that every part of the municipality is within an address area. In other countries, the concept of address area names is less strict and based on local tradition or specific needs.

NOTE 2 In some situations an address area name is not required to obtain unambiguousness; instead the purpose is to make the complete address more informative and descriptive, adding a well known place name (e.g. of a village or community) to the address. This is particularly useful if the municipality or post code covers a large area.

Autrement dit, si on dispose d'un lieu-dit avec numérotation, ne conviendrait-il pas de basculer cette voie dans la classe "Street" car elle se comporte exactement comme une voie classique ? Et réserver ainsi cette classe Locality / AdressArea à ces cas moins normés, les lieux-dits sans adresses et les regroupements d'adresses ?

Add table constraints where needed

http://docs.peewee-orm.com/en/latest/peewee/models.html?highlight=constraints#table-constraints

• Municipality.insee
• Municipality.siren
• BaseFantoir.fantoir
• ZipCode.code
• HouseNumber.cea
• HouseNumber.cia

[MCD] renommer HouseNumber en Address

Bonjour,

J'ai un vrai problème avec le terme "HouseNumber".

Une adresse / un numéro d'adresse peut en effet être attribué à bien d'autre chose qu'une maison d'habitation. Je le pensais avant l'open lab du 15/12 et les discussions qui ont eu lieu m'ont renforcé dans ma position.
Je viens de relire la spécification de données INSPIRE et je propose d'adopter le terme "Adress" qui est bien plus souple et générique et qui reflètera mieux les données disponibles dans la BAN.

Je met ici en pj l'analyse de l'AITF de 2011 sur la version 2.0 produite pour l'appel à commentaires. Les lecteurs retrouveront certains concepts.

[aux admins : impossible de téléverser un PDF malgré que ce soit indiqué comme format autorisé. taille = 424 ko]

adapt MCD to store (Street, Locality, and others) as Zone, and not each ones in own entity

idea to unify theses zones in the same entity, for example Zone, w/ a new column, as type (varchar), to specify the zone

• Street
• Locality
  +
• old Municipality
• District

gestion des changements pour Addok (diff)

la BAN se propose de mettre à disposition dans un espace public (accessible via HTTP) des fichiers dump au format JSON, pour les applications clientes

• export complet (1x par jour)
• export delta, de manière périodique (1x par minute par exemple)

nous avons un besoin de mises à jour régulière de la base REDIS d'ADDOK, qui nécessite un enrichissement spécifique de cet export delta (il faut en effet l'ensemble des adresses filles modifiées)

pour ce faire, plusieurs solutions sont envisageables:

1. export supplémentaire spécifique pour ADDOK (schéma ci-dessus)

   👎 charge activité de la BAN
   👍 traitement unitaire de cet export

2. enrichissement de l'API CRUD : Get pour une ressource DIFF, de manière à récupérer ce flux spécifique pour la ressource demandée
   dans ce cas, le middleware client consomme les exports delta, et pour chaque ligne générique, demande via l'API toutes les adresses modifiées, au format attendu par ADDOK

   👎 traitement multiple de cet export, pour chaque instance ADDOK
   👍 charge activité déportée côté client (enfin un peu 😔)
   👍 gestion affinée de la ressource DIFF (il me semble aujourd'hui en retour complet)

3. un middleware prend en charge la génération de cet export spécifique, en interrogeant l'API BAN et en générant alors lui-même le flux attendu par ADDOK

   👎 traitement multiple de cet export, pour chaque instance ADDOK
   👎 complexité accrue, pour chaque implémentation d'une instance ADDOK à jour
   👍 charge activité déportée côté client (enfin un peu 😔)