REL Service API - HERCULES SGI

Overview

The REL Service (Relaciones) manages relationships and cross-references between entities across different modules in the HERCULES SGI platform. It enables linking and tracking connections between projects, applications, ethics reviews, intellectual property, and other entities.

Base URL: http://localhost:4284 (development)
Service Path: /relaciones

Authentication

All endpoints require a valid OAuth2 access token with appropriate permissions.

Authorization: Bearer <access_token>

Relations Endpoints

List Relations

Retrieve a paginated and filtered list of relations between entities.

GET /relaciones

string

RSQL filter query for searching relations

string

Sorting criteria (e.g., id,asc)

page

number

Page number (0-indexed)

size

number

Page size

Example Request:

curl -X GET "http://localhost:4284/relaciones?q=tipoEntidadOrigen=='PROYECTO'&page=0&size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "content": [
    {
      "id": 1,
      "tipoEntidadOrigen": "PROYECTO",
      "entidadOrigenRef": "proyecto-123",
      "tipoEntidadDestino": "SOLICITUD",
      "entidadDestinoRef": "solicitud-456",
      "tipoRelacion": "DERIVED_FROM",
      "observaciones": "Project created from application"
    },
    {
      "id": 2,
      "tipoEntidadOrigen": "PROYECTO",
      "entidadOrigenRef": "proyecto-123",
      "tipoEntidadDestino": "MEMORIA",
      "entidadDestinoRef": "memoria-789",
      "tipoRelacion": "REQUIRES_ETHICS_REVIEW",
      "observaciones": "Ethics review required for this project"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 10
}

Get Relation by ID

Retrieve a specific relation by its identifier.

GET /relaciones/{id}

number

required

Relation identifier

Example Request:

curl -X GET "http://localhost:4284/relaciones/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": 1,
  "tipoEntidadOrigen": "PROYECTO",
  "entidadOrigenRef": "proyecto-123",
  "tipoEntidadDestino": "SOLICITUD",
  "entidadDestinoRef": "solicitud-456",
  "tipoRelacion": "DERIVED_FROM",
  "observaciones": "Project created from application",
  "fechaCreacion": "2024-01-15T10:30:00Z"
}

Create Relation

Create a new relation between two entities.

POST /relaciones

tipoEntidadOrigen

string

required

Source entity type: PROYECTO, SOLICITUD, CONVOCATORIA, MEMORIA, INVENCION, etc.

entidadOrigenRef

string

required

Reference ID of the source entity

tipoEntidadDestino

string

required

Destination entity type

entidadDestinoRef

string

required

Reference ID of the destination entity

tipoRelacion

string

required

Relation type: DERIVED_FROM, REQUIRES_ETHICS_REVIEW, GENERATES_IP, RELATED_TO, etc.

observaciones

string

Optional notes about the relation

Example Request:

curl -X POST "http://localhost:4284/relaciones" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoEntidadOrigen": "PROYECTO",
    "entidadOrigenRef": "proyecto-789",
    "tipoEntidadDestino": "INVENCION",
    "entidadDestinoRef": "invencion-101",
    "tipoRelacion": "GENERATES_IP",
    "observaciones": "Patent filed for research outcome"
  }'

Response:

{
  "id": 3,
  "tipoEntidadOrigen": "PROYECTO",
  "entidadOrigenRef": "proyecto-789",
  "tipoEntidadDestino": "INVENCION",
  "entidadDestinoRef": "invencion-101",
  "tipoRelacion": "GENERATES_IP",
  "observaciones": "Patent filed for research outcome",
  "fechaCreacion": "2024-03-05T14:20:00Z"
}

Update Relation

Update an existing relation.

PUT /relaciones/{id}

number

required

Relation identifier to update

Example Request:

curl -X PUT "http://localhost:4284/relaciones/3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoEntidadOrigen": "PROYECTO",
    "entidadOrigenRef": "proyecto-789",
    "tipoEntidadDestino": "INVENCION",
    "entidadDestinoRef": "invencion-101",
    "tipoRelacion": "GENERATES_IP",
    "observaciones": "Patent granted for research outcome"
  }'

Delete Relation

Delete a relation between entities.

DELETE /relaciones/{id}

number

required

Relation identifier to delete

Example Request:

curl -X DELETE "http://localhost:4284/relaciones/3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Relation Model

number

Unique relation identifier

tipoEntidadOrigen

string

Source entity type

entidadOrigenRef

string

Source entity reference ID

tipoEntidadDestino

string

Destination entity type

entidadDestinoRef

string

Destination entity reference ID

tipoRelacion

string

Type of relationship between entities

observaciones

string

Optional notes or description

fechaCreacion

string

ISO 8601 timestamp when the relation was created

Entity Types

The following entity types can be related:

Type	Module	Description
`PROYECTO`	CSP	Research project
`SOLICITUD`	CSP	Grant application
`CONVOCATORIA`	CSP	Grant call
`MEMORIA`	ETI	Ethics review report
`EVALUACION`	ETI	Ethics evaluation
`INVENCION`	PII	Invention disclosure
`SOLICITUD_PROTECCION`	PII	IP protection request
`PRODUCCION_CIENTIFICA`	PRC	Scientific production item

Relation Types

Common relation types include:

Type	Description
`DERIVED_FROM`	Destination was created from source
`REQUIRES_ETHICS_REVIEW`	Source requires ethics review (destination)
`GENERATES_IP`	Source generated intellectual property (destination)
`RELATED_TO`	Generic bidirectional relation
`PART_OF`	Source is part of destination
`FUNDS`	Source provides funding for destination

RSQL Filter Examples

# Find all relations from a specific project
q=tipoEntidadOrigen=='PROYECTO';entidadOrigenRef=='proyecto-123'

# Find ethics review requirements
q=tipoRelacion=='REQUIRES_ETHICS_REVIEW'

# Find IP generated from projects
q=tipoEntidadOrigen=='PROYECTO';tipoRelacion=='GENERATES_IP'

# Relations involving a specific entity (as source or destination)
q=entidadOrigenRef=='proyecto-123',entidadDestinoRef=='proyecto-123'

Common Use Cases

Track Project-to-Application Lineage

curl -X GET "http://localhost:4284/relaciones?q=tipoEntidadOrigen=='PROYECTO';tipoRelacion=='DERIVED_FROM'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Find All Ethics Reviews for a Project

curl -X GET "http://localhost:4284/relaciones?q=entidadOrigenRef=='proyecto-123';tipoRelacion=='REQUIRES_ETHICS_REVIEW'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List IP Generated from a Project

curl -X GET "http://localhost:4284/relaciones?q=entidadOrigenRef=='proyecto-123';tipoRelacion=='GENERATES_IP'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Integration with Other Services

The REL service integrates with:

CSP Service - Links projects, applications, and grant calls
ETI Service - Tracks ethics review requirements
PII Service - Connects projects to intellectual property
PRC Service - Associates projects with scientific production

Relations are automatically created by other services when certain actions occur (e.g., creating a project from an application), but can also be managed manually through these APIs.

Error Responses

status

number

HTTP status code

error

string

Error type

message

string

Human-readable error message

Example Error Response:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid entity type: INVALID_TYPE"
}

CSP Service

Projects and applications

ETI Service

Ethics reviews

PII Service

Intellectual property

Architecture

System architecture and integration

Services

Authentication

​Overview

​Authentication

​Relations Endpoints

​List Relations

​Get Relation by ID

​Create Relation

​Update Relation

​Delete Relation

​Relation Model

​Entity Types

​Relation Types

​RSQL Filter Examples

​Common Use Cases

​Track Project-to-Application Lineage

​Find All Ethics Reviews for a Project

​List IP Generated from a Project

​Integration with Other Services

​Error Responses

​Related Documentation

CSP Service

ETI Service

PII Service

Architecture

Build docs developers (and LLMs) love

Overview

Authentication

Relations Endpoints

List Relations

Get Relation by ID

Create Relation

Update Relation

Delete Relation

Relation Model

Entity Types

Relation Types

RSQL Filter Examples

Common Use Cases

Track Project-to-Application Lineage

Find All Ethics Reviews for a Project

List IP Generated from a Project

Integration with Other Services

Error Responses

Related Documentation