Comprendre le processus de publication

Pour l'API de dépôt, chaque publication s'appelle une révision, car techniquement, c'est une API de versionnage de fichier.

Une publication en 4 requêtes

Swagger de l'API de démo : https://plateforme-bal.adresse.data.gouv.fr/api-depot-demo/api

Étape 1 : création de la revision avec contexte d'authentification

Lors de la création d'une revision, vous aurez besoin :

• du token (jeton)

• du codeCommune

• le contexte utilisateur doit être renseigné. Il est composé de 3 champs optionnels (mais fortement recommandés) :

  • Nom de la personne nomComplet qui effectue le dépôt.

  • Nom de l'organisation organisation

  • Champs libre clé/valeur extras : peut-être utilisé pour stocker des identifiants internes au client, des données additionnelles actuellement non supportées par l'API, mais jugées utiles par l'éditeur. Attention ces champs sont publiques.

POST  /communes/27115/revisions                  --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx           --> Obligatoire
Content-Type: application/json

# Body
{
  "context": {
    "nomComplet": "Alice Bob",          --> Optionnel mais recommandé
    "organisation": "Mairie de Breux-sur-Avre",  --> Optionnel mais recommandé
    "extras": {
      "internal_id": "9990"
    }                                            --> Optionnel
  }
}

Réponse :

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"               --> revisionId pour l'étape 2,3 et 4
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {},
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[e-mail]"
  },
  "status": "pending",
  "isReady": false,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

Étape 2 : téléversement du fichier au format BAL 1.3 ou 1.4

• Pour le téléversement, vous aurez besoin : du token, de la revisionId et du fichier BAL.

• En option : le Content-Length du fichier et sa signature MD5

PUT /revisions/507f191e810c19729de860ea/files/bal --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx            --> Obligatoire
Content-Type: text/csv
Content-Length: 2133                              --> Optionnel mais recommandé
Content-MD5: 1234567890abcdedf1234567890abcdedf   --> Optionnel mais recommandé

# Body (Binary)
@@@ fichier BALC @@@                              --> Obligatoire, taille max 50mb

Réponse :

200 Success


# Header
Content-Type: application/json

# Body
{
  "id": "507f199710c19729de860ea",            --> Identifiant du fichier
  "revisionId": "507f191e810c19729de860ea",   --> Identifiant de révision
  "type": "bal",
  "size": 2133,
  "hash": "51ca0bce566423b6c5a321e911438c57195adf747d066e0dd4b212d43c0f4c6e",
  "createdAt": "2020-01-01T00:00:00Z"
}

Étape 3 : validation

• Pour la validation, vous aurez besoin du token, de la revisionId

• Vous pouvez vérifier vos BAL directement avec le validateur BAL en ligne ou ligne de commande

POST  /revisions/507f191e810c19729de860ea/compute       --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx                  --> Obligatoire

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[e-mail]"
  },
  "status": "pending",
  "isReady": true,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

• Si le fichier soumis n'est pas valide, la valeur isReady reste à false et validation.valid est false.

Étape 4 : publication de la revision

• Pour la publication vous aurez besoin du token, de la revisionId

• Lorsque isReady :true la revision peut être publiée.

POST  /revisions/507f191e810c19729de860ea/publish   --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx              --> Obligatoire

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[e-mail]"
  },
  "status": "published",
  "isCurrent": true,     
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": "2020-01-01T01:00:00Z"
}

• Si isCurrent : true alors la BAL est en production !