Documentación de la API REST y de la API de Python

Este documento proporciona la referencia de la API REST de Requirements & Systems Portal. Mediante la API REST, los usuarios pueden obtener y modificar datos de Requirements & Systems Portal, e incluso escribir datos de vuelta en Requirements & Systems Portal y así actualizar la información. Además, esto le brinda la posibilidad de conectarse/integrarse con otras aplicaciones o apps.

Acceso a la API REST en Requirements & System Portal mediante tokens

Para acceder a la API REST en la aplicación Requirements & Systems Portal en Altium A365, los usuarios pueden generar los tokens navegando al menú Settings y seleccionando User Tokens. Dentro de la página de configuración de User Tokens, encontrará la dirección de la API para su implementación específica. Esta dirección es necesaria para realizar llamadas a la API.

Haga clic en el icono “+” en la página User Tokens para generar un nuevo token. Cada token es válido durante 3 months y debe regenerarse después de que expire.

Para consumir la API usando el access_token, es necesario agregar un token mediante un "Bearer ..." usando el tipo de aplicación "JSON" en el encabezado Authorization de la solicitud HTTP.

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
    }
}'

o, usando requests, puede enviar el token de acceso de esta manera

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)

Documentación de la API de Python

La API de Python le permite acceder y actualizar objetos en su implementación con código Python.

Instale el paquete necesario de la API de Python con pip:

pip install valispace

Importe el módulo de la API en un script de Python:

import valispace

e inicialícelo con

valispace = valispace.API()

Puede encontrar más información sobre las funcionalidades y funciones de la API aquí. El paquete de la API de Python está licenciado bajo la licencia MIT, lo que significa que cualquiera puede contribuir al código clonando el repositorio de GitHub.

Endpoints

Los usuarios pueden acceder a los endpoints en la página rest. Para acceder a la página, agregue “rest/” al final de la URL de la API que se puede encontrar en Requirements & Systems Portal en Settings y “User Tokens”. La página Rest muestra Django Swagger con todos los endpoints existentes.

Existen métodos “GET”, “POST”, “PUT”, “PATCH” y “DELETE”.

Cada objeto en Requirements & Systems Portal tiene su propio ID; puede usarlo para buscar y recuperar la información del propio objeto. El ID del objeto puede verse directamente en Requirements & Systems Portal o en la URL al hacer clic en el objeto dentro de Requirements & Systems Portal.

Por ejemplo, si usa la función get para obtener información de vali a través de rest, puede usar el siguiente endpoint para obtener los detalles del vali.

GET /rest/valis/{vali-id}/

Uso de GET para recuperar la información del vali

De manera similar, puede usar los métodos para recuperar/actualizar o publicar distintos objetos como Blocks, tags, valis, textvalis, requirements, specifications, verification methods, etc. Puede buscar los endpoints en la página rest.

Filtrado de objetos por proyectos

Además de la autenticación, puede usar el método "GET" para recuperar objetos como Valis o Requirements dentro de la implementación. Si necesita filtrar los resultados según un proyecto específico, puede hacerlo aprovechando las capacidades de filtrado, siempre que el endpoint esté configurado en consecuencia. Por ejemplo, para recuperar requirements asociados con el proyecto 24, puede usar la siguiente solicitud GET:

GET /rest/requirements/?project=24

Esta funcionalidad se muestra en el video a continuación para una comprensión más clara.

Funciones integradas

Dentro de Requirements & Systems Portal, cada vez que un usuario escribe texto en el campo de texto, el texto se guarda en el backend en formato HTML
. El formato HTML conserva las referencias de formato a valis u otros objetos. Por lo tanto, si está obteniendo la información de requirements, es posible que reciba el texto HTML en su importación. Para evitar esto, hemos implementado dos funciones que pueden ser útiles para convertir los campos HTML a solo texto o a formato HTML con los valis convertidos a texto. Las funciones son clean_text y clean_html.

Función clean_text

La función clean_text convierte todos los formatos HTML y las referencias a objetos dentro del campo en texto. Sin embargo, en este caso, también se pierde el formato. Por ejemplo, también se pierde el formato si tiene una lista, tablas o color. Puede usarla como se muestra a continuación.

Aquí, estoy aplicando el filtro para el proyecto 24 y solicitando que se devuelva el texto limpio para el texto y la justificación del campo. La salida sería esta para esta acción específica.

Requirements después de usar la función Clean_text

Función clean_html

La función clean_html mantiene las opciones de formato del texto, pero convierte las referencias/objetos como valis en texto. Si el texto contiene opciones de formato como listas, color de fondo, tablas, etc., esta información se conserva.

Requirements después de usar la función clean_html

Preguntas frecuentes:

¿Cómo encontrar el endpoint correcto?

Navegar por numerosos endpoints con nombres similares puede resultar confuso. Si en algún momento tiene dudas sobre un endpoint específico, le recomendamos ponerse en contacto con nuestra página de soporte de Altium para obtener aclaraciones. Como alternativa, puede aprovechar la función "network" de su navegador para observar qué endpoints se activan al realizar acciones dentro del front end del software.

Como ejemplo, considere el proceso de creación de un Block. En este caso, el endpoint asociado puede identificarse como una solicitud "POST" a "/rest/components"; esta información puede determinarse fácilmente inspeccionando la actividad de red durante la acción. A continuación, se proporciona una breve demostración de este enfoque en el video corto.

¿Cómo se obtienen/publican los verification methods (VM) y Blocks de un requirement?

Un requirement en Requirements & Systems Portal puede estar asociado con múltiples verification methods (VM), cada uno de los cuales, a su vez, puede tener múltiples Blocks adjuntos. Se admiten varios tipos de verification method, incluidos rules, test, inspection, analyses, review y VM personalizados. Cada tipo de verification method se identifica de forma única por su propio ID.

Puede usar el endpoint adecuado para recuperar los ID de estos tipos de verification method.

GET /rest/requirements/verification-methods/

Por ejemplo, para obtener los ID de los tipos de Verification method para el proyecto con id 24, puede usar el siguiente endpoint

GET /rest/requirements/verification-methods/?project=24

Lista de verification methods del proyecto

Para obtener los verification methods vinculados a un requirement específico, Requirements & Systems Portal crea un objeto dedicado conocido como "Requirement-VMS". Este objeto tiene su identificador único (ID), al que se puede acceder mediante el siguiente endpoint:

GET /rest/requirements/requirement-vms/

Por ejemplo, este requirement, SPC-002 con ID 2165, tiene un verification method de tipo “Rules”, y el object id de requirment-vms es 2203.

Si usamos el endpoint, “/rest/requirements/requirement-vms/2203 ” obtenemos la siguiente respuesta.

Claves y valores de requirment-vms

Al inspeccionar el objeto "Requirement-vms", notará que el method ID "20" corresponde al Verification Method "Rules", según la lista de tipos de verification method obtenida anteriormente. Al incorporar esta información en su script, asegúrese de asignar el method ID al tipo de verification method correspondiente.

Además, dentro del objeto "Requirement-vms", hay referencias a dos component-vms. Estos ID de component-vm representan los Blocks adjuntos a los Requirement Verification Methods. Al interactuar con estos Blocks mediante programación, utilice estos ID en su script según corresponda.

El endpoint para acceder a los component-vms sería

GET /rest/requirements/component-vms/{id}

Cuando obtenga los detalles de los component-vms, el campo component le proporciona el id del Block con el que puede asociar el nombre del Block.

Component-vms