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

Esta página ofrece la documentación de referencia de la API REST de Requirements Portal. Con la API REST, puede obtener y modificar datos de Requirements Portal, o incluso escribir datos en Requirements Portal y actualizar así la información. Además, le permite conectarse o integrarse con otras aplicaciones.

Acceso a la API REST de Requirements Portal mediante tokens

Para acceder a la API REST de Requirements Portal, puede generar los tokens en la página Settings – User Tokens (a la que se accede haciendo clic en el icono  de la esquina superior derecha, seleccionando Settings en el menú que aparece y, a continuación, seleccionando User Tokens en la lista del panel izquierdo). En esta página encontrará la API address de su implementación específica. Esta dirección es necesaria para realizar llamadas a la API.

Haga clic en el icono + de la esquina inferior derecha de la página Settings – User Tokens para generar un nuevo token. Cada token es válido durante 3 months y debe volver a generarse cuando caduque.

Para utilizar la API con el access_token, es necesario añadir un token mediante «Bearer ...» al encabezado Authorization de la solicitud HTTP, utilizando el tipo de aplicación «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
    }
}'

También puede enviar el token de acceso mediante requests de la siguiente 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 a los objetos de su implementación y actualizarlos mediante código Python.

Instale el paquete de la API de Python necesario 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 se distribuye bajo la licencia MIT, lo que significa que cualquier persona puede contribuir al código clonando el repositorio de GitHub.

Endpoints

Los usuarios pueden acceder a los endpoints en la página de Swagger. Para acceder a esta página, añada swagger/ al final de la URL de la API que encontrará en la página Settings – User Tokens. La página muestra Django Swagger con todos los endpoints existentes.

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

Cada objeto de Requirements Portal tiene su propio ID. Puede utilizarlo para buscar y recuperar la información del objeto. El ID del objeto se puede ver directamente en Requirements Portal o en la URL al hacer clic en el objeto dentro de Requirements Portal.

Por ejemplo, si utiliza la función GET para obtener información del historial de un requisito a través de Swagger, puede utilizar el siguiente endpoint para obtener los detalles del historial del requisito.

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

Obtención de la información del historial de un requisito mediante GET

Del mismo modo, puede utilizar los métodos para recuperar, actualizar o enviar distintos objetos, como bloques, etiquetas, valis, textvalis, requisitos, especificaciones, métodos de verificación, etc. Puede buscar los endpoints en la página de Swagger.

Filtrado de objetos por proyecto

Además de la autenticación, puede utilizar el método GET para recuperar objetos como Valis o requisitos dentro de la implementación. Si necesita filtrar los resultados por un proyecto específico, puede hacerlo utilizando las funciones de filtrado, siempre que el endpoint esté configurado para ello. Por ejemplo, para recuperar los requisitos asociados al proyecto 24, puede utilizar la siguiente solicitud GET:

GET /rest/requirements/?project=24

Esta funcionalidad se muestra en el siguiente vídeo para facilitar su comprensión.

Funciones integradas

En Requirements Portal, cuando un usuario introduce texto en un campo de texto, este se guarda en el backend en formato HTML. El formato HTML conserva el formato y las referencias a valis u otros objetos. Por tanto, al obtener la información de los requisitos, es posible que la importación incluya texto HTML. Para evitarlo, hemos implementado dos funciones que pueden resultar útiles para convertir los campos HTML en texto sin formato o conservar el formato HTML convirtiendo los valis en texto. Estas funciones son clean_text y clean_html.

Función clean_text

La función clean_text convierte en texto todo el formato HTML y las referencias a objetos del campo. Sin embargo, en este caso también se pierde el formato. Por ejemplo, si hay listas, tablas o colores, su formato también se pierde. Puede utilizar esta función como se muestra a continuación.

Aquí se aplica el filtro para el proyecto 24 y se solicita el texto sin formato del texto y de la justificación del campo. El resultado de esta acción específica sería el siguiente.

Requisitos después de utilizar la función clean_text

Función clean_html

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

Requisitos después de utilizar la función clean_html

Preguntas frecuentes

¿Cómo encontrar el endpoint correcto?

Navegar entre numerosos endpoints con nombres similares puede resultar confuso. Si tiene dudas sobre un endpoint específico, le recomendamos que se ponga en contacto con nosotros a través de nuestra página de soporte de Altium para obtener aclaraciones. También puede utilizar la función «Red» de su navegador para observar qué endpoints se activan al realizar acciones en la interfaz del software.

Como ejemplo, considere el proceso de creación de un bloque. En este caso, el endpoint asociado se puede identificar como una solicitud «POST» a «/rest/components». Esta información se puede identificar fácilmente inspeccionando la actividad de red durante la acción. En el breve vídeo que aparece a continuación se muestra una demostración de este procedimiento.