Interroger le tableau de bord de la plate-forme Web pour les outils de référence

Jeremy Wagner

Publié le 4 mars 2025

La baseline a été créée par l'équipe Chrome et est désormais définie par le WebDX Community Group. Baseline clarifie les fonctionnalités interopérables entre les navigateurs. Il est conçu pour vous aider à identifier les fonctionnalités que vous pouvez ou ne pouvez pas utiliser dans tous les principaux moteurs de navigateur. Toutefois, vous devez trouver un moyen d'identifier ces caractéristiques.

Heureusement, vous pouvez interroger les fonctionnalités qui sont nouvellement ou largement disponibles dans la référence de base à l'aide du tableau de bord Web Platform, qui est alimenté par le package npm web-features. Vous pouvez également accéder à ces informations à l'aide de son API HTTP pour intégrer les données de référence dans votre workflow d'outils. Ce guide vous explique comment procéder.

Grammaire de requête de référence pertinente du tableau de bord de la plate-forme Web

Le tableau de bord de la plate-forme Web utilise une grammaire de requête spécifique pour vous aider à rechercher la compatibilité des fonctionnalités Web. Vous pouvez utiliser cette grammaire de requête directement dans le tableau de bord.

Lorsque vous saisissez du texte dans le champ de recherche en haut de la page, plusieurs paramètres de requête s'affichent. Vous pouvez les utiliser pour filtrer les fonctionnalités Web.

La grammaire des requêtes est expressive, ce qui vous offre une grande flexibilité pour filtrer les fonctionnalités Web affichées dans le tableau de bord. La capture d'écran suivante montre comment utiliser le paramètre de requête id pour affiner la recherche et trouver une fonctionnalité spécifique :

La grammaire des requêtes est documentée, mais il n'est pas nécessaire de la connaître entièrement pour trouver les données de référence des fonctionnalités. Vous pouvez utiliser n'importe laquelle de ces options dans le tableau de bord, mais en voici quelques-unes qui sont particulièrement utiles :

• baseline_status : utilisez ce paramètre pour filtrer les caractéristiques selon trois valeurs énumérées :
  • limited : renvoie les fonctionnalités dont la compatibilité avec les navigateurs est limitée. Si vous filtrez par cette valeur, vous ne recevrez que les fonctionnalités qui n'ont pas atteint l'état de référence.
  • newly : renvoie les fonctionnalités nouvellement disponibles dans la version de référence.
  • widely : renvoie les fonctionnalités de base largement disponibles, c'est-à-dire celles qui sont de base depuis au moins 30 mois. Il s'agit de fonctionnalités que vous pouvez utiliser sans vous soucier de la compatibilité avec les navigateurs ni des polyfills.
• baseline_date : utilise un format YYYY-MM-DD..YYYY-MM-DD pour spécifier une limite supérieure et inférieure pour le moment où les fonctionnalités ont atteint la référence. Par exemple, pour trouver toutes les fonctionnalités au cours d'une année, utilisez une valeur telle que 2024-01-01..2025-01-01.
• id : identifiant d'une fonctionnalité donnée. Ces identifiants sont définis dans le package web-features. Par exemple, l'entrée de fonctionnalité pour Promise.try() correspond à un ID de promise-try.
• group : l'un des nombreux noms de groupes énumérés pour les caractéristiques. Ce critère est utile si vous ne souhaitez interroger qu'un certain sous-ensemble de fonctionnalités de la plate-forme Web. Par exemple, vous pouvez filtrer une liste de caractéristiques CSS avec une valeur de css.

Bien que l'interface du tableau de bord soit certainement utile, elle repose sur une API HTTP que vous pouvez interroger directement. Par exemple, voici un point de terminaison qui récupère toutes les fonctionnalités de référence nouvellement disponibles :

https://api.webstatus.dev/v1/features?q=baseline_status:newly

Structure de la réponse JSON

La réponse JSON que vous recevez de l'API HTTP a une forme cohérente pour chaque fonctionnalité. La réponse renvoyée contient une propriété data au premier niveau. Cette propriété contient un tableau de toutes les fonctionnalités correspondantes. Bien que cette liste ne soit pas exhaustive des champs disponibles dans la réponse JSON, voici quelques champs utiles pour Baseline :

• baseline : contient des informations générales sur l'état de référence d'une fonctionnalité donnée, avec les sous-champs suivants :
  • status : état de référence d'une fonctionnalité. Les valeurs peuvent être limited, newly ou widely. Remarque : Il s'agit du seul sous-champ si status a la valeur limited.
  • low_date : indique la date à laquelle la fonctionnalité donnée est devenue "Nouvellement disponible" dans la référence. Ce champ n'apparaît que si status est défini sur newly ou widely.
  • high_date : indique la date à laquelle la fonctionnalité donnée est devenue largement disponible dans la version de référence. Ce champ n'est disponible que si status est défini sur widely.
• feature_id : ID de la fonctionnalité. Par exemple, pour la grille CSS, il s'agirait d'une valeur "grid".
• name : nom mis en forme de la caractéristique. Dans certains cas, il peut être similaire à feature_id, mais il est généralement différent. Par exemple, la valeur feature_id pour Promise.try() est "promise-try", tandis que le champ name pour la même caractéristique est "Promise.try()".
• spec : ce champ contient un sous-champ nommé links, qui est un tableau de liens vers des spécifications et d'autres ressources.

Il existe d'autres champs, qui contiennent souvent des informations sur la version et la date d'implémentation de la fonctionnalité par certains navigateurs compatibles, des données sur les tests de la plate-forme Web et d'autres informations qui peuvent vous intéresser ou non.

Exemples de requêtes

Maintenant que vous avez une brève explication de certains des paramètres de requête disponibles, examinez quelques exemples de requêtes que vous pouvez utiliser dans vos outils et scripts pour sélectionner des fonctionnalités d'état Web qui pourraient être utiles pour votre workflow.

Obtenir les données d'une seule caractéristique

Pour vous familiariser avec l'API, commencez par un exemple de base qui récupère les données d'une seule fonctionnalité Web.

// Specify and encode the query for a query string:
const query = encodeURIComponent('id:grid');

// Construct the URL:
let url = `https://api.webstatus.dev/v1/features?q=${query}`;

// Fetch the resource:
const response = await fetch(url);

if (response.ok) {
  // Convert the response to JSON:
  const { data } = await response.json();

  // Log data for each feature to the:
  console.log(data);
}

Dans ce cas, nous spécifions un paramètre id avec une valeur de grid pour obtenir des informations sur la compatibilité des fonctionnalités pour la grille CSS, qui est largement disponible dans Baseline. Vous pouvez utiliser ces informations, par exemple, pour détecter l'utilisation de la fonctionnalité et informer les utilisateurs qu'ils peuvent l'utiliser dans tous les moteurs de navigateur modernes sans se soucier de la compatibilité.

Toutefois, ce n'est qu'un début, et l'API HTTP peut faire beaucoup plus pour vous que d'obtenir des données pour une seule fonctionnalité.

Accéder à toutes les fonctionnalités de référence nouvellement disponibles et largement disponibles

Imaginons que vous souhaitiez disposer d'un script qui récupère toutes les fonctionnalités qui sont soit "Nouvellement disponibles", soit "Largement disponibles" dans la référence. Cela peut être utile, par exemple, si vous disposez d'un script qui s'exécute à un certain intervalle et que vous souhaitez obtenir une liste mise à jour qui évolue à mesure que les fonctionnalités passent de la disponibilité limitée à l'état de référence :

const query = encodeURIComponent('-baseline_status:limited');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Cette requête ne récupère pas toutes les fonctionnalités de référence nouvellement et largement disponibles, mais seulement les 100 premières. Si le nombre d'entités récupérées dépasse cette limite, un champ metadata se trouve au niveau supérieur de la réponse JSON et peut contenir jusqu'à deux sous-champs :

• next_page_token : chaîne contenant un jeton que vous pouvez ajouter à la chaîne de requête de la requête GET envoyée au backend. Lorsque vous l'utiliserez et que vous récupérerez à nouveau les données du backend webstatus.dev, il renverra le prochain lot de fonctionnalités correspondantes. Remarque : Ce champ ne sera pas disponible si la requête actuelle renvoie moins de 100 résultats ou si elle se trouve à la fin de l'ensemble de résultats.
• total : entier indiquant le nombre total de caractéristiques disponibles pour la requête actuelle.

Ces champs sont utiles pour la pagination. Avec eux, nous pouvons essayer le code suivant pour obtenir tous les résultats d'une requête qui renvoie une grande quantité de données :

async function queryWebStatusDashboard (query, token) {
  const urlBase = 'https://api.webstatus.dev/v1/features?q=';
  let queryUrl = `${urlBase}${encodeURIComponent(query)}`;

  if (token) {
    queryUrl += `&page_token=${encodeURIComponent(token)}`;
  }

  const response = await fetch(queryUrl);

  if (response.ok) {
    const { data, metadata } = await response.json();

    console.log(data);

    // See if there's a page token in this query:
    if ('next_page_token' in metadata) {
      const { next_page_token } = metadata;
      queryWebStatusDashboard(query, next_page_token);
    } else {
      console.log('All results collected');
    }
  }
}

// Make the first query, and if there are more
// than 100 entries, the function will run
// recursively until all features are fetched
queryWebStatusDashboard('-baseline_status:limited');

Obtenir toutes les nouvelles fonctionnalités CSS de référence

Imaginons que vous soyez un ingénieur spécialisé dans les CSS et que vous souhaitiez savoir quelles fonctionnalités CSS deviennent des fonctionnalités de référence nouvellement disponibles. C'est un cas d'utilisation idéal pour la valeur de requête group, ainsi que pour l'utilisation de l'opérateur AND lors de l'interrogation de webstatus.dev :

const query = encodeURIComponent('baseline_status:newly AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Lorsque vous spécifiez une valeur css pour group, vous pouvez interroger toutes les nouvelles fonctionnalités de référence. Si vous souhaitez étendre le champ d'application pour inclure également les fonctionnalités CSS largement disponibles de référence, vous pouvez utiliser l'approche du dernier exemple de code et utiliser l'opérateur de négation avec une requête telle que -baseline_status:limited AND group:css'.

Vous pouvez également interroger le champ snapshot, qui est utile pour trouver les fonctionnalités JavaScript qui font partie d'un ensemble spécifique de fonctionnalités ECMAScript. Le code suivant vérifie toutes les nouvelles fonctionnalités de référence qui font partie de l'instantané ecmascript-2023 :

const query = encodeURIComponent('baseline_status:newly AND snapshot:ecmascript-2023');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Obtenir toutes les fonctionnalités de référence dans une plage de dates

Vous pouvez interroger le champ baseline_date pour trouver toutes les fonctionnalités qui sont devenues de référence au cours d'une période donnée :

const query = encodeURIComponent('baseline_status:widely AND baseline_date:2022-01-01..2022-12-31 AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

L'exemple de code précédent interroge les fonctionnalités CSS qui sont devenues largement disponibles dans la référence à un moment donné en 2022. La syntaxe des requêtes pour baseline_date vous permet de spécifier une date de début et une date de fin, séparées par ...

Conclusion

Les requêtes de ce guide sont destinées à être un point de départ pour vous permettre de commencer à tester la façon d'interroger le backend webstatus.dev. Avec n'importe quel nombre de paramètres de requête disponibles, vous devriez pouvoir obtenir des résultats spécifiques à votre application.

Savoir comment interroger l'API HTTP du tableau de bord Web Platform vous permet de créer des outils qui peuvent être utiles pour votre travail et de savoir si les fonctionnalités que vous souhaitez utiliser pour votre projet sont suffisamment compatibles avec les navigateurs. Cela signifie que vous pouvez créer des applications Web à l'aide de fonctionnalités de navigateur modernes que vous pouvez utiliser en toute sécurité, ce qui offre une expérience de développement beaucoup plus agréable.