Documentation de `/api/datasets/:id` - statuer sur le champ "history" (documenter ? ou supprimer ?)

[thbar]

En lien avec:

• 3324

Actuellement, la "doc" swagger de l'API requête /api/datasets/:id (voir ici) indique comme exemple de retour:

{
  "aom": "string",
  "community_resources": [
    {
      "community_resource_publisher": "string",
      "end_calendar_validity": "string",
      "format": "string",
      "metadata": {},
      "original_resource_url": "string",
      "original_url": "string",
      "start_calendar_validity": "string",
      "title": "string",
      "updated": "string",
      "url": "string"
    }
  ],
  "created_at": "2023-07-17",
  "licence": "string",
  "name": "string",
  "resources": [
    {
      "conversions": {
        "GeoJSON": {
          "filesize": 0,
          "last_check_conversion_is_up_to_date": "2023-07-17T14:38:03.754Z",
          "stable_url": "string"
        },
        "NeTEx": {
          "filesize": 0,
          "last_check_conversion_is_up_to_date": "2023-07-17T14:38:03.754Z",
          "stable_url": "string"
        }
      },
      "end_calendar_validity": "string",
      "format": "string",
      "metadata": {},
      "original_url": "string",
      "start_calendar_validity": "string",
      "title": "string",
      "updated": "string",
      "url": "string"
    }
  ],
  "updated": "string"
}

Il y a quelques temps, a été ajouté le champ "history" qui donne un peu d'historique sur les ressources.

Cet ajout a été fait pro-activement sans demande extérieure.

Du coup je me pose la question de la documentation API (qui est dans nos objectifs trimestriels): souhaite-t-on documenter cette partie (et la supporter officiellement, ce qui peut introduire des complications comme https://github.com/etalab/transport-site/issues/3324), ou est-il possible de la supprimer?

À discuter avec @etalab/transport-bizdev.

Par ailleurs je ne sais pas à quel point d'autres champs sont incorrects dans cette documentation, il faudra mettre au propre également.

[thbar]

@etalab/transport-tech je vais documenter un peu mieux les deux opérations principales de l'API. Est-ce qu'on conserve pour le moment l'history et je le documente?

Je pourrais éventuellement indiquer que c'est en "beta" et qu'on n'est pas sûr de le laisser ici, par exemple.

Je suis plus embêté par le fait de le supprimer, ça me semble utile, et le fait d'avoir ça dans la payload du dataset de detail me paraît plutôt bien.

[AntoineAugusti]

@thbar Ça me parait être une bonne idée de le garder, uniquement sur l'endpoint pour un JDD spécifique

[thbar]

Ok gardons le !

[thbar]

Je mentionnerai ce point dans:

• 3350