KPIs API

This API allows managing Key Performance Indicators (KPIs) in the system. It provides endpoints to create, read, update, and delete KPIs, as well as to perform queries and filtering.

The KPI Object

The KPI object represents a key performance indicator in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "revenue_growth",
  "persona": "business",
  "label": "Revenue Growth",
  "description": "Measures the percentage increase in revenue",
  "value": {
    "target": 10.5,
    "redRange": [0, 5],
    "yellowRange": [5, 8],
    "greenRange": [8, 15]
  },
  "history": [
    {
      "referenceId": "ref123",
      "executionId": "exec456",
      "value": {
        "target": 10.0,
        "redRange": [0, 4],
        "yellowRange": [4, 7],
        "greenRange": [7, 12]
      },
      "updatedAt": "2023-04-01T12:00:00Z"
    }
  ],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-04-01T12:00:00Z"
}

Attributes

Attribute	Description	Type
`id`	Unique identifier of the KPI	String
`key`	Unique key of the KPI	String
`persona`	Type of entity associated with the KPI	String
`label`	Label or name of the KPI	String
`description`	Detailed description of the KPI	String
`value`	Current value and ranges of the KPI	Object
`history`	Change history of the KPI	Array of Object
`createdAt`	Creation date and time of the KPI	String (ISO 8601)
`updatedAt`	Date and time of the last update	String (ISO 8601)

Available Operations

Create a New KPI

Creates a new KPI in the system.

POST /v1/kpis

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Reference ID	String	No
`executionId`	Execution ID	String	No
`label`	Label or name of the KPI	String	Yes
`description`	Detailed description of the KPI	String	Yes
`key`	Unique key of the KPI	String	Yes
`persona`	Type of entity associated with the KPI	String	No
`value`	Value and ranges of the KPI	Object	Yes

Example Request:

{
  "label": "Revenue Growth",
  "description": "Measures the percentage increase in revenue",
  "key": "revenue_growth",
  "persona": "business",
  "value": {
    "target": 10.5,
    "redRange": [0, 5],
    "yellowRange": [5, 8],
    "greenRange": [8, 15]
  }
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update an Existing KPI

Updates the information of an existing KPI.

PATCH /v1/kpis/:kpi_id

Path Parameters:

Parameter	Description
`kpi_id`	ID of the KPI to update

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Reference ID	String	No
`executionId`	Execution ID	String	No
`label`	New label or name of the KPI	String	No
`description`	New description of the KPI	String	No
`value`	New value and ranges of the KPI	Object	No
`date`	Update date	String	No

Example Request:

{
  "label": "Annual Revenue Growth",
  "value": {
    "target": 12.0,
    "redRange": [0, 6],
    "yellowRange": [6, 10],
    "greenRange": [10, 18]
  }
}

Successful Response:

The response will be the updated KPI object.

Retrieve a KPI

Retrieves the information of a specific KPI.

GET /v1/kpis/:kpi_id

Path Parameters:

Parameter	Description
`kpi_id`	ID of the KPI to retrieve

Successful Response:

The response will be the complete KPI object, as described above.

Delete a KPI

Deletes a KPI from the system.

DELETE /v1/kpis/:kpi_id

Path Parameters:

Parameter	Description
`kpi_id`	ID of the KPI to delete

Successful Response:

Status code 204 (No Content) if the deletion was successful.

List KPIs

Retrieves a paginated list of KPIs with filtering and sorting options.

GET /v1/kpis

Query Parameters:

Parameter	Description	Type
`key`	Filter by KPI key	String
`persona`	Filter by entity type	String
`search`	Text to search in the KPIs	String
`page`	Page number (default: 1)	Integer
`per-page`	Items per page (default: 10)	Integer
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

The response will be a paginated list of KPI objects.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page