Every HTTP call in the Alliance Research Indicators client goes throughDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/alliance-research-indicators-client/llms.txt
Use this file to discover all available pages before exploring further.
ApiService or a domain service that delegates to it. Components never call HttpClient directly. This page explains the service URL conventions, the MainResponse<T> contract that every response conforms to, the representative endpoints exposed by the Main API, and how to handle errors correctly.
The three backend services
Environment variables insrc/environments/environment*.ts supply the base URL for each service. The jWtInterceptor inspects outgoing request URLs to determine which authentication header format to use.
| Variable | Service | When to use it |
|---|---|---|
mainApiUrl | Main API (NestJS) | All core business logic — results CRUD, indicators, users, CLARISA controlled-list proxying, dashboards, authorization, and projects |
textMiningUrl | Text-Mining microservice | AI/NLP auto-fill and content extraction for result form fields |
fileManagerUrl | File Manager microservice | Multipart evidence file uploads; the service returns a persistent URL that is then stored on the result record |
The Main API and File Manager accept
Authorization: Bearer <token> headers. The Text-Mining service expects the token in an access-token header and, for multipart requests, also embedded in the request FormData as a token field. The jWtInterceptor handles these differences automatically.The MainResponse<T> envelope
Every response from the Main API is wrapped in a standard envelope. The TypeScript interface is defined in src/app/shared/interfaces/responses.interface.ts:
successfulRequest is the primary signal of whether the request succeeded from the application’s point of view — it can be false even when the HTTP status code is 200 (for example, when the server reports a business-logic failure). Always check this field before consuming data.
Reading a response
ApiService call patterns
ApiService is provided in root and injected wherever HTTP calls are needed. Method naming follows a consistent convention:
| Prefix | HTTP verb | Example |
|---|---|---|
GET_ | GET | GET_GeneralInformation(id) |
POST_ | POST | POST_Result(body) |
PATCH_ | PATCH | PATCH_GeneralInformation(id, body) |
DELETE_ | DELETE | DELETE_Result(resultCode) |
Promise<MainResponse<T>>. They delegate to ToPromiseService (src/app/shared/services/to-promise.service.ts), which wraps the HttpClient observable into a promise and applies request options (loading triggers, result interceptor opt-in, etc.).
Representative endpoints
The following endpoints are consumed byApiService and reflect the API surface documented in the Detailed Design §4.3.
Authorization
Authorization
Indicators
Indicators
| Method | Path | Description |
|---|---|---|
GET | /indicator-types | All indicator type definitions |
GET | /indicator-types/:id | Single indicator type |
GET | /indicators | Full indicator catalog |
GET | /indicators/:id | Single indicator |
GET | /maturity-levels | Maturity level reference data |
GET | /indicators/results-amount/current-user | Result count per indicator for the current user |
CLARISA controlled lists
CLARISA controlled lists
| Method | Path | Description |
|---|---|---|
GET | /tools/clarisa/institutions | Institution list (with location and type) |
GET | /tools/clarisa/institutions-types | Institution type hierarchy |
GET | /tools/clarisa/sdgs | Sustainable Development Goals |
GET | /tools/clarisa/levers | Alliance strategic levers |
GET | /tools/clarisa/sdg-targets | SDG target reference data |
GET | /tools/clarisa/impact-areas | CGIAR impact areas |
GET | /tools/clarisa/countries | Country list (optional is-sub-national filter) |
GET | /tools/clarisa/languages | Language list |
GET | /tools/clarisa/regions | Region list |
GET | /tools/clarisa/sub-nationals/country/:isoAlpha2 | Sub-national units by country |
GET | /tools/clarisa/innovation-types | Innovation type reference data |
GET | /tools/clarisa/innovation-readiness-levels | Innovation readiness level reference data |
Results CRUD
Results CRUD
| Method | Path | Description |
|---|---|---|
GET | /v2/results | Paginated result list (supports filtering, sorting, search) |
POST | /results | Create a new result |
GET | /results/:id/general-information | Load general-information tab |
PATCH | /results/:id/general-information | Save general-information tab |
GET | /results/:id/geo-location | Load geographic scope tab |
PATCH | /results/:id/geo-location | Save geographic scope tab |
GET | /results/:id/alignments | Load alliance-alignment tab |
PATCH | /results/:id/alignments | Save alliance-alignment tab |
GET | /results/evidences/principal/:id | Load evidence tab |
PATCH | /results/evidences/by-result-id/:id | Save evidence tab |
DELETE | /results/:code/delete | Delete a result |
GET | /results/validate-title | Check whether a result title is unique |
GET | /results/versions/:resultCode | Retrieve available versions of a result |
Result lifecycle / status
Result lifecycle / status
| Method | Path | Description |
|---|---|---|
POST | /results/status/workflow/change-status/:code/to-status/:status | Submit or transition a result through the MEL workflow |
GET | /results/status/:id | Current status of a result |
GET | /results/status/review-statuses | All review status options |
GET | /results/status/workflow/result/:code/next-step | Next permitted workflow step for a result |
GET | /results/green-checks/:resultCode | Green-check completion status for all tabs |
Results center, dashboards, projects
Results center, dashboards, projects
| Method | Path | Description |
|---|---|---|
GET | /results/status/result-amount/current-user | Results grouped by status for the current user |
GET | /results/last-updated/current-user | Most recently updated results for the current user |
GET | /agresso/contracts/results/current-user | Contracts (projects) linked to the current user |
GET | /agresso/contracts/find-contracts | Search contracts with optional filters |
GET | /agresso/contracts/:id/results/count | Result count for a specific contract |
GET | /results/contracts/:contractId | All results linked to a contract |
GET | /results/general-report/all | Full general report dataset |
Error handling
successfulRequest === false
Never swallow a failed response. Pass it through to ActionsService so the user receives a human-readable toast or alert.
401 — token expiry
Handled automatically byjWtInterceptor. The interceptor attempts a token refresh and retries the original request once. If the refresh also fails, the user is logged out and redirected to /login. Components do not need to handle 401 explicitly.
409 — conflict / duplicate
A 409 response means the server detected a duplicate (for example, a result with the sameplatform_code + official_code already exists). Surface the structured “link to existing” prompt — do not retry the request blindly. The httpErrorInterceptor intentionally suppresses the automatic error toast for 409s, leaving the component to handle the flow.
Validation errors
When the server returns field-level validation failures, they arrive inerrorDetail.errors. Render these inline next to the offending form field rather than showing a generic toast.
Error tracking
ThehttpErrorInterceptor automatically sends all HTTP errors to the remote error-tracking endpoint configured in environment.saveErrorsUrl. It also starts a 5-second timer on every request — if no response arrives, a “pending” (slow-request) event is logged. No additional error reporting is needed in individual services or components for standard HTTP failures.