TimePerformance 12 mars 2023

TimePerformance API version 4

Il s’agit d’une nouvelle version de l’API car des modifications ne sont pas rétrocompatibles. La version 3 de l’API sera maintenue jusqu’au 31 décembre 2023.

Cette mise à jour de l’API contient:

• Des nouvelles API 
• Nouvelle documentation au format OpenAPI
• Modification de certaines API existantes dans le but de simplifier ou d’uniformiser (cf. guide de migration ci-dessous)

Nouvelle documentation au format OpenAPI

Une nouvelle documentation a été mise en ligne qui est générée depuis un fichier de spécification au format OpenAPI v3.0. Cette nouvelle version permet de tester l’API directement depuis la documentation.

Il est aussi possible de récupérer le fichier de spécification de l’API au format OpenAPI afin de l’utiliser dans un environnement de développement. Il existe des plugins pour les IDE (ex: « OpenAPI (Swagger) Editor » pour VS Code) ou des outils de génération de code.

Nouvelles API

Une dizaine d’API ont été ajoutées principalement pour importer ou modifier des données.

Pour l’instant, les API de modification concernent les projets, les fiches projet, les utilisateurs et les équipes projets. Dans les futures versions, il sera aussi possible de modifier les tâches, les livrables, les phases…

Les API de modification des données nécessitent un accès Back Office disponible uniquement en version Premium, contrairement aux API qui extraient des données disponibles dès la version Standard. La version Premium est en cours de développement. Les fonctionnalités Premium sont actuellement offertes aux Clients ayant choisi l’option SSO.

Guide de migration de la v3 à la v4

Les API existantes conservent leur interface et leurs paramètres. Pour passer à la v4, il suffit de remplacer le v3 par v4 dans l’url de l’API et de supprimer toutes les extensions .json ou .txt .

https://pma.timeperformance.com/api/v3/users.json
                      ⇓
https://pma.timeperformance.com/api/v4/users

Pour certaines API, la structure des réponses a été légèrement modifiée. Voici ci-dessous la liste de ces modifications et la liste des API impactées par ces modifications.

Modif. 1: L’information de la demi-journée pour les affectations est désormais stockée dans une seule propriété date au lieu de deux (day et dayPart).

{
  day: "2022-12-12",
  dayPart: "AM"
}
     ⇓
{
   date: "2022-12-12 AM"
}

Modif. 2: La propriété « state » d’un projet contient une structure (avec l’id, le nom et l’externalId…) de l’état au lieu du nom seul sous la forme d’une string.

state: "En Cours"
     ⇓
state: { 
   id: 24,
   name: "En Cours",
   type: "projectstate",
   externalId: "S-78",
   finished: false
}

Modif. 3: La structure de données de l’API Project Baseline Report a changé en remplaçant la valeur et l’écart par rapport à la valeur précédente par la valeur courante et la valeur précédente. 

{
  workload: {
     value: {
        val: 419,
        unit: "jh"
     },
     variance: {
        val: 0,
        unit: "%"
     }
  }
}
     ⇓
{
   workload: {
      current: 419,
      previous: 419
   }
}

Modif. 4: Ajout des droits applicatifs pour les utilisateurs (aucune migration nécessaire).

rights: {
   limitedAccess: false,
   administrator: true,
   manager: true,
   pmo: false,
   createProject: true,
   manageSelf: true,
   appAccess: true
}

Modif. 5: Suppression du format texte pour les listes d’identifiant. Seul le format JSON (tableau d’entiers) est supporté.

Modif. 6: Suppression de l’extension « .json » dans l’URL des API. Cela concerne toutes les API.

Modif. 7: L’URL de API /users/assignments/syncUnavailabilities a été changée pour intégrer l’identifiant de l’utilisateur

Liste des API impactées

URL de l’API & numéro de la modification	1	2	3	4	5	7
/projects/{id}/assignments	✔
/projects		✔
/projects/{id}/summary		✔
/projects/{id}/progressReport		✔
/projects/{id}/baselineReport		✔	✔
/projects/getIdFromName					✔
/portfolios/getIdFromName					✔
/portfolios/{id}/progressReport		✔
/users				✔
/users/{id}/assignments	✔
/users/{id}/assignments/syncUnavailabilities	✔					✔