Documentazione delle API REST e Python

Questa pagina fornisce la documentazione di riferimento per l'API REST di Requirements Portal. Utilizzando l'API REST, puoi recuperare e modificare i dati di Requirements Portal, oppure scrivere dati al suo interno e aggiornare così le informazioni. Inoltre, puoi connetterti o integrarti con altre applicazioni.

Accesso all'API REST di Requirements Portal tramite token

Per accedere all'API REST di Requirements Portal, puoi generare i token nella pagina Settings – User Tokens (accessibile facendo clic sull'icona  in alto a destra, selezionando Settings dal menu visualizzato e quindi selezionando User Tokens dall'elenco nel riquadro a sinistra). In questa pagina troverai il API address relativo alla tua specifica istanza. Questo indirizzo è necessario per effettuare le chiamate API.

Fai clic sull'icona + in basso a destra nella pagina Settings – User Tokens per generare un nuovo token. Ogni token è valido per 3 months e deve essere rigenerato dopo la scadenza.

Per utilizzare l'API con access_token, è necessario aggiungere un token tramite "Bearer ..." all'intestazione Authorization della richiesta HTTP, utilizzando il tipo di applicazione "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
    }
}'

In alternativa, utilizzando requests, puoi inviare il token di accesso in questo modo

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)

Documentazione dell'API Python

L'API Python consente di accedere agli oggetti della tua istanza e di aggiornarli tramite codice Python.

Installa il pacchetto API Python necessario con pip:

pip install valispace

Importa il modulo API in uno script Python:

import valispace

e inizializzalo con

valispace = valispace.API()

Ulteriori informazioni sulle funzionalità e sulle funzioni dell'API sono disponibili qui. Il pacchetto API Python è distribuito con licenza MIT, il che significa che chiunque può contribuire al codice clonando il repository GitHub.

Endpoint

Gli utenti possono accedere agli endpoint nella pagina Swagger. Per accedere alla pagina, aggiungi swagger/ alla fine dell'URL dell'API, disponibile nella pagina Settings – User Tokens. La pagina mostra Django Swagger con tutti gli endpoint esistenti.

Sono disponibili i metodi GET, POST, PUT, PATCH e DELETE.

Ogni oggetto in Requirements Portal ha un proprio ID. Puoi utilizzarlo per cercare e recuperare le informazioni sull'oggetto stesso. L'ID dell'oggetto è visibile direttamente in Requirements Portal oppure nell'URL quando fai clic sull'oggetto in Requirements Portal.

Ad esempio, se utilizzi la funzione GET per ottenere informazioni sulla cronologia di un requisito tramite Swagger, puoi utilizzare il seguente endpoint per recuperarne i dettagli.

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

Recupero delle informazioni sulla cronologia del requisito tramite GET

Allo stesso modo, puoi utilizzare i metodi per recuperare, aggiornare o inviare diversi oggetti, come blocchi, tag, valis, textvalis, requisiti, specifiche, metodi di verifica, ecc. Puoi cercare gli endpoint nella pagina Swagger.

Filtraggio degli oggetti per progetto

Oltre all'autenticazione, puoi utilizzare il metodo GET per recuperare oggetti come Valis o requisiti all'interno dell'istanza. Se devi filtrare i risultati in base a un progetto specifico, puoi sfruttare le funzionalità di filtraggio, purché l'endpoint sia configurato di conseguenza. Ad esempio, per recuperare i requisiti associati al progetto 24, puoi utilizzare la seguente richiesta GET:

GET /rest/requirements/?project=24

Questa funzionalità è illustrata nel video qui sotto per facilitarne la comprensione.

Funzioni integrate

In Requirements Portal, ogni volta che un utente digita del testo nel campo di testo, questo viene salvato nel backend in formato HTML. Il formato HTML conserva la formattazione e i riferimenti ai valis o ad altri oggetti. Pertanto, quando recuperi le informazioni sui requisiti, potresti ottenere testo HTML nell'importazione. Per evitare questo problema, abbiamo implementato due funzioni che possono essere utili per convertire i campi HTML in testo semplice oppure in HTML con i valis convertiti in testo. Le funzioni sono clean_text e clean_html.

Funzione clean_text

La funzione clean_text converte in testo tutta la formattazione HTML e tutti i riferimenti agli oggetti presenti nel campo. In questo caso, tuttavia, anche la formattazione viene persa. Ad esempio, se sono presenti elenchi, tabelle o colori, la relativa formattazione viene persa. Puoi utilizzare questa funzione come mostrato di seguito.

In questo esempio, applico il filtro per il progetto 24 e richiedo il testo semplice per il testo e la motivazione del campo. Il risultato di questa specifica operazione è il seguente.

Requisiti dopo l'utilizzo della funzione clean_text

Funzione clean_html

La funzione clean_html mantiene la formattazione del testo, ma converte in testo i riferimenti e gli oggetti, come i valis. Se il testo contiene elementi di formattazione come elenchi, colori di sfondo, tabelle, ecc., queste informazioni vengono conservate.

Requisiti dopo l'utilizzo della funzione clean_html

Domande frequenti

Come trovare l'endpoint corretto?

Orientarsi tra numerosi endpoint con nomi simili può creare confusione. In caso di dubbi su un endpoint specifico, ti invitiamo a contattare la nostra pagina di supporto Altium per ottenere chiarimenti. In alternativa, puoi utilizzare la funzionalità "Rete" del browser per osservare quali endpoint vengono richiamati quando esegui operazioni nel front end del software.

Come esempio, considera la procedura di creazione di un blocco. In questo caso, l'endpoint associato può essere identificato come una richiesta "POST" a "/rest/components"; questa informazione è facilmente individuabile esaminando l'attività di rete durante l'operazione. Nel breve video qui sotto viene fornita una dimostrazione sintetica di questo approccio.