TimePerformance API version 3

API version 3

Cette mise à jour de l’API contient:

• 4 nouvelles API pour répondre aux demandes de nos utilisateurs
• des simplifications des structures des réponses de certaines API existantes

Il s’agit d’une nouvelle version de l’API car certaines modifications ne sont pas rétrocompatibles.

La version 2 de l’API sera maintenue jusqu’au 30 septembre 2021 afin de laisser le temps de migrer les codes client. Une communication a été envoyée aux contacts techniques inscrits sur la mailing liste pour les informer de changements minimes (suppression de champs superflus) dans les réponses de la version 2 qui prendront effet dès la mise en ligne de la version 3.

Le guide de migration ci-dessous a pour but de faciliter la mise à jour les codes des clients de l’API.

La date prévue de mise en ligne de la version 3 de l’API est le 3 juin.

4 Nouvelles API

Les nouvelles API sont:

1. Project Configuration fournit la configuration des profils pour un projet (cf. documentation)
2. Organizational Breakdown Structure retourne la structure de l’organisation (cf. documentation)
3. List of Skill Profiles retourne la liste des profils configurés dans l’administration (cf. documentation)
4. List of Non-Project Activities retourne la liste des autres activités et des indisponibilités configurées dans l’administration (cf. documentation)

Guide de migration de la v2 à la v3

Les API existantes conservent leur interface et leurs paramètres. Pour passer à la v3, il suffit de remplacer le v2 par v3 dans l’url de l’API.

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

Pour certaines API, la structure des réponses a été légèrement modifiée pour la simplifier. Voici la liste de ces modifications ainsi que la liste des API impactées.

Modif. 1: L’unité est représentée par la chaîne de caractères de son symbole au lieu d’une structure. 

costUnit: {
  id: 1948
  name: "Euro"
  type: "COST"
  symbol: "€"
}
     ⇓
costUnit: "€"

Modif. 2: L’attribut « state » d’un projet est représenté par son nom au lieu d’une structure. 

state: {
  val: 24
  str: "En Cours"
}
     ⇓
state: "En Cours"

Modif. 3: Les attributs de type énumération (liste fixe de valeurs) sont représentés par leur code au lieu d’une structure code + libellé. 

rights: {
  val: "MEMBER"
  str: "Équipe"
}
     ⇓
rights: "MEMBER"

Modif. 4: Remplacement dans la structure d’un utilisateur des attributs obsName et obsPath par une structure. 

{...
  obsName: "Recherche et développement"
  obsPath: "ACME » Direction des Systèmes d'Information » Recherche et développement"
}
     ⇓
{...
  obs: {
    id: 39
    name: "Recherche et développement"
    path: "ACME » Direction des Systèmes d'Information » Recherche et développement"
    type: "obs"
    externalId: "RD-1"
  }
}

Modif. 5: Pour un utilisateur, fusion des structures cost et rate en une seule . 

{...
  cost: {
    val: 624
    str: "624 €"
    unit: "€"
  }
  rate: {
    val: "DAILY_VAR"
    str: "par jour"
  }
}
     ⇓
{...
  costRate: {
    val: 624
    unit: "€"
    rateMode: "DAILY_VAR"
  }
}

Modif. 6: Pour les indicateurs avec une unité, suppression de la chaîne de caractères représentant le nombre formatté. 

...
  value: {
    val: 306671.32391131297
    str: "306 671 €"
    unit: "€"
  }
...
     ⇓
...
  value: {
    val: 306671.32391131297
    unit: "€"
  }
...

Modif. 7: Dans la feuille de route d’un projet, simplification de la structure fournissant les estimations de charge par profil.  (note: « unit » était redondant avec effortUnit à la racine de la feuille de route)

effortByProfile: [
  {
    val: 30
    str: "30"
    unit: "jh"
    profile: {
      id: 32
      name: "Analyste"
      type: "resourceprofile"
    }
    effort: 30
  }
...]
     ⇓
effortByProfile: [
  {
    profile: {
      id: 32
      name: "Analyste"
      type: "resourceprofile"
    }
    effort: 30
  }
...]

Liste des API impactées

URL de l’API & numéro de la modification	1	2	3	4	5	6	7
/portfolios/…/progressReport.json	✔	✔
/projects.json		✔
/projects/…/summary.json		✔
/projects/…/team.json			✔	✔	✔
/projects/…/progressReport.json	✔	✔
/projects/…/expenses.json						✔
/projects/…/actualsTimeseries	✔
/projects/…/baselineReport.json		✔				✔
/projects/…/roadmap.json	✔						✔
/users.json				✔	✔