Documentation de l’API REST et de l’API Python

Cette page présente la documentation de référence de l’API REST de Requirements Portal. L’API REST vous permet de récupérer et de modifier des données de Requirements Portal, ou encore d’y écrire des données afin de mettre à jour les informations. Elle vous permet également de vous connecter à d’autres applications ou de les intégrer.

Accéder à l’API REST de Requirements Portal à l’aide de jetons

Pour accéder à l’API REST de Requirements Portal, vous pouvez générer des jetons sur la page Settings – User Tokens (accessible en cliquant sur l’icône  en haut à droite, en sélectionnant Settings dans le menu qui s’affiche, puis User Tokens dans la liste du volet de gauche). Sur cette page, vous trouverez API address pour votre déploiement. Cette adresse est nécessaire pour effectuer des appels à l’API.

Cliquez sur l’icône + en bas à droite de la page Settings – User Tokens pour générer un nouveau jeton. Chaque jeton est valide pendant 3 months et doit être régénéré après son expiration.

Pour utiliser l’API avec access_token, vous devez ajouter un jeton sous la forme « Bearer ... » dans l’en-tête Authorization de la requête HTTP, en utilisant le type de contenu « JSON ».

curl --location 'http://deployment_name/rest/requirements/versions/search/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer hO2lwhLZsYOgXPNVI' \
--data '{
    "size": 10,
    "query_filters": {
        "object_id": 93
    }
}'

Vous pouvez également utiliser requests pour envoyer le jeton d’accès comme suit

access_token = 'Generated_Access_token'
api_url = 'Api_Address'

# workspace id and component type

workspace_id = 1
component_type_name = "CompA"

# Define headers with the access token
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',  # Adjust content type as needed
}

# Make a GET request (you can use other HTTP methods like POST, PUT, etc.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)

Documentation de l’API Python

L’API Python vous permet d’accéder aux objets de votre déploiement et de les mettre à jour à l’aide de code Python.

Installez le package d’API Python nécessaire avec pip :

pip install valispace

Importez le module de l’API dans un script Python :

import valispace

puis initialisez-le avec

valispace = valispace.API()

Vous trouverez plus d’informations sur les fonctionnalités et les fonctions de l’API ici. Le package d’API Python est distribué sous licence MIT, ce qui signifie que chacun peut contribuer au code en clonant le dépôt GitHub.

Points de terminaison

Les utilisateurs peuvent accéder aux points de terminaison sur la page Swagger. Pour accéder à cette page, ajoutez swagger/ à la fin de l’URL de l’API disponible sur la page Settings – User Tokens. Cette page affiche Django Swagger avec tous les points de terminaison existants.

Les méthodes disponibles sont GET, POST, PUT, PATCH et DELETE.

Chaque objet de Requirements Portal possède son propre identifiant. Vous pouvez l’utiliser pour rechercher et récupérer les informations de l’objet. L’identifiant de l’objet est visible soit directement dans Requirements Portal, soit dans l’URL lorsque vous cliquez sur l’objet dans Requirements Portal.

Par exemple, si vous utilisez la méthode GET pour obtenir des informations sur l’historique d’une exigence via Swagger, vous pouvez utiliser le point de terminaison suivant pour récupérer les détails de cet historique.

GET /rest/requirements/{requirement-id}/history/

Récupérer les informations de l’historique d’une exigence à l’aide de GET

De même, vous pouvez utiliser les méthodes pour récupérer, mettre à jour ou créer différents objets, tels que des blocs, des étiquettes, des valis, des textvalis, des exigences, des spécifications, des méthodes de vérification, etc. Vous pouvez rechercher les points de terminaison sur la page Swagger.

Filtrer les objets par projet

En plus de l’authentification, vous pouvez utiliser la méthode GET pour récupérer des objets tels que des Valis ou des exigences au sein du déploiement. Si vous devez filtrer les résultats selon un projet spécifique, vous pouvez exploiter les fonctionnalités de filtrage, à condition que le point de terminaison soit configuré en conséquence. Par exemple, pour récupérer les exigences associées au projet 24, vous pouvez utiliser la requête GET suivante :

GET /rest/requirements/?project=24

La vidéo ci-dessous illustre cette fonctionnalité pour vous aider à mieux la comprendre.

Fonctions intégrées

Dans Requirements Portal, lorsqu’un utilisateur saisit du texte dans un champ de texte, celui-ci est enregistré côté serveur au format HTML. Le format HTML conserve la mise en forme ainsi que les références aux valis ou à d’autres objets. Ainsi, lorsque vous récupérez les informations des exigences, votre import peut contenir du texte HTML. Pour éviter cela, nous avons implémenté deux fonctions permettant de convertir les champs HTML en texte brut, ou de conserver la mise en forme HTML tout en convertissant les valis en texte. Il s’agit des fonctions clean_text et clean_html.

Fonction clean_text

La fonction clean_text convertit en texte l’ensemble du contenu HTML et des références aux objets présents dans le champ. Toutefois, la mise en forme est également perdue. Par exemple, les listes, les tableaux ou les couleurs ne sont pas conservés. Vous pouvez utiliser cette fonction comme indiqué ci-dessous.

Ici, je filtre les résultats pour le projet 24 et je demande à obtenir le texte brut du texte et de la justification du champ. Voici le résultat de cette opération.

Exigences après utilisation de la fonction clean_text

Fonction clean_html

La fonction clean_html conserve la mise en forme du texte, mais convertit en texte les références et les objets tels que les valis. Si le texte contient des éléments de mise en forme comme des listes, une couleur d’arrière-plan, des tableaux, etc., ces informations sont conservées.

Exigences après utilisation de la fonction clean_html

Questions fréquentes

Comment trouver le bon point de terminaison ?

Il peut être difficile de s’y retrouver parmi les nombreux points de terminaison portant des noms similaires. Si vous avez un doute concernant un point de terminaison spécifique, nous vous invitons à consulter notre page d’assistance Altium pour obtenir des précisions. Vous pouvez également utiliser la fonctionnalité « Réseau » de votre navigateur pour observer quels points de terminaison sont appelés lorsque vous effectuez des actions dans l’interface du logiciel.

Prenons l’exemple de la création d’un bloc. Dans ce cas, le point de terminaison associé correspond à une requête « POST » vers « /rest/components ». Vous pouvez facilement identifier cette information en examinant l’activité réseau pendant l’action. La courte vidéo ci-dessous présente brièvement cette approche.