Anuncio

API REST v1

Lea y escriba artefactos, enlaces, módulos y líneas base desde sus propios programas, scripts o su pipeline de CI.

Autenticación

La API REST requiere el complemento ETRM API a una suscripción Single o Team propia. Sin ambas suscripciones responde con el estado 403 y el código de error subscription_required.

Cree una clave de acceso en Perfil, Acceso API y envíela en cada solicitud en la cabecera Authorization. La clave actúa con sus derechos en los grupos. Las claves sin derecho de escritura solo pueden leer.

curl -H "Authorization: Bearer etrm_…" https://engineering-toolbox.com/etrm/api/v1/

Fundamentos

  • Dirección base: https://engineering-toolbox.com/etrm/api/v1/. Las solicitudes y respuestas son JSON (UTF-8).
  • Los proyectos tienen el mismo ID que en las direcciones de la interfaz. Los artefactos se identifican por su número (#12 pasa a ser 12).
  • Derechos como en la interfaz: leer requiere el rol READ; crear, modificar y eliminar, el rol EDIT.
  • Las listas se paginan: parámetros limit (máximo 500, por defecto 100) y offset; la respuesta contiene count y next_offset.
  • Los textos son texto enriquecido restringido (HTML). El servidor los depura igual que al guardar en la interfaz.
  • Cada cambio crea una nueva versión en el historial y marca los enlaces como sospechosos, igual que en la interfaz.

Proyectos

GETprojects/Sus proyectos con rol (los archivados con ?archived=1).
GETprojects/<id>/Proyecto con configuración: tipos de artefacto, atributos con valores permitidos, tipos de enlace, módulos.
GETprojects/<id>/metrics/Indicadores como en el panel: alcance, cobertura, enlaces sospechosos, volatilidad, indicaciones de redacción.

Artefactos

GETprojects/<id>/artifacts/Lista. Filtros: type (varios), module, tag (varios, basta uno), q (texto completo), changed_since (ISO 8601), attr.<clave>=<valor>, deleted=1 (incluida la papelera).
POSTprojects/<id>/artifacts/Crear. Opcionalmente con tags (lista), module, parent (número de un encabezado en el módulo) y position.
GETprojects/<id>/artifacts/<nr>/Un artefacto con módulos y enlaces.
PATCHprojects/<id>/artifacts/<nr>/Modificar title, text, type, attributes y tags (sustituye toda la lista). rev (estado actual) es obligatorio; si el artefacto ha cambiado entretanto, se devuelve 409 con el estado actual. En attributes, null elimina un valor.
DELETEprojects/<id>/artifacts/<nr>/A la papelera (se puede restaurar en la interfaz).

Ejemplo: crear un requisito de sistema

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
  -d '{"type": "systemanforderung", "title": "Zellspannung messen",
       "text": "<p>Das BMS muss jede Zellspannung mit ±2 mV messen.</p>",
       "attributes": {"status": "entwurf", "prioritaet": "muss"}, "module": 3, "parent": 12}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/

Respuesta (abreviada)

{"number": 131, "id": "#131", "uid": "6f1c…", "type": "systemanforderung", "title": "Zellspannung messen",
 "text": "<p>…</p>", "attributes": {"status": "entwurf", "prioritaet": "muss"}, "tags": [], "rev": 1,
 "deleted": false, "quality": [], "url": "…/artifacts/131/"}

El campo quality contiene las indicaciones de la revisión de redacción (p. ej. términos vagos o puntos abiertos).

Etiquetas

GETprojects/<id>/tags/Etiquetas del proyecto con color, active y count (artefactos fuera de la papelera).
GETprojects/<id>/artifacts/<nr>/tags/Etiquetas de un artefacto.
POSTprojects/<id>/artifacts/<nr>/tags/Añadir etiquetas: tags (lista de nombres). Los nombres desconocidos se crean en el proyecto. added indica lo que se ha añadido.
DELETEprojects/<id>/artifacts/<nr>/tags/<name>/Quitar una etiqueta del artefacto. Se mantiene en el proyecto; removed es null si no estaba asignada.
POSTprojects/<id>/tags/<name>/artifacts/Acción masiva como en la tabla: asignar una etiqueta a varios artefactos (numbers, como máximo 500).
DELETEprojects/<id>/tags/<name>/Eliminar una etiqueta no utilizada del proyecto (solo administradores del grupo). Respuesta: name y deleted. Si sigue asignada a artefactos (también en la papelera), la respuesta es 409 tag_in_use con count.

Se aplican las mismas reglas que en la interfaz: no se distingue entre mayúsculas y minúsculas, los nombres tienen como máximo 50 caracteres y ninguna coma. Añadir y quitar se pueden repetir sin riesgo, no cambian rev y aparecen en el historial del artefacto. Codifique en la URL los nombres con caracteres especiales.

Solo se pueden eliminar las etiquetas no utilizadas. Las líneas base y el historial conservan los nombres, por lo que los estados anteriores no cambian.

Ejemplo: añadir dos etiquetas

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
  -d '{"tags": ["Sicherheit", "ASIL B"]}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/131/tags/

Respuesta (abreviada)

{"number": 131, "tags": ["ASIL B", "Sicherheit"], "added": ["ASIL B"]}

Módulos

GETprojects/<id>/modules/Lista de módulos con structure_rev.
GETprojects/<id>/modules/<modul>/Estructura en orden del documento con número (1.2, 1.2-3), profundidad, artefacto, parent (número del encabezado) y position. El encabezado ETag contiene el estado de la estructura.
POSTprojects/<id>/modules/<modul>/artifacts/Insertar un artefacto existente: artifact (número), opcionalmente parent y position. Sin ellos, al final del nivel superior.
GETprojects/<id>/modules/<modul>/artifacts/<nr>/Posición de un artefacto en el módulo.
PATCHprojects/<id>/modules/<modul>/artifacts/<nr>/Cambiar el encabezado (parent, null para el nivel superior) y/o position. Los artefactos subordinados se mueven con él.
DELETEprojects/<id>/modules/<modul>/artifacts/<nr>/Quitar del módulo. El artefacto permanece en el proyecto con su número, UID, historial y enlaces; los artefactos subordinados ocupan su lugar.

position cuenta desde 0 dentro del nivel; los artefactos en la papelera no cuentan. Un artefacto aparece como máximo una vez por módulo; en varios módulos es el mismo artefacto.

Cambios simultáneos: envíe el ETag leído en el encabezado If-Match (o como structure_rev en el contenido). Si la estructura ha cambiado entretanto, también en la interfaz, recibirá 409 con la estructura actual en current. Sin él no se comprueba.

Ejemplo: insertar un artefacto en primer lugar bajo el encabezado #12

curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" -H 'If-Match: "s-7"' \
  -d '{"artifact": 131, "parent": 12, "position": 0}' \
  https://engineering-toolbox.com/etrm/api/v1/projects/<id>/modules/3/artifacts/

Líneas base

GETprojects/<id>/baselines/Lista.
POSTprojects/<id>/baselines/Crear un nuevo estado: name, opcionalmente note y module.
GETprojects/<id>/baselines/<b>/Una línea base; con ?payload=1 el estado completo e inmutable.
GETprojects/<id>/baselines/<b>/compare/Diferencias con el estado actual o, con ?with=<b>, con otra línea base: nuevos, eliminados, modificados, desplazados, enlaces.

Error

Los errores se devuelven como JSON con error (código) y message (texto); con datos no válidos, además details por campo.

400datos no válidos (validation, invalid_json, invalid_parameter)
401token ausente, desconocido o revocado
403El rol no es suficiente, el token solo puede leer o no hay un complemento ETRM API activo (subscription_required)
404no encontrado (también proyectos de los que no es miembro)
405método no permitido
409conflicto: el artefacto o la estructura del módulo se ha modificado entretanto (la respuesta contiene current), el artefacto está en la papelera o ya está en el módulo (already_bound)
{"error": "validation", "message": "Die Angaben sind nicht gültig.", "details": {"prioritaet": ["Pflichtfeld."]}}