api-usage
/api-usage
Opisuje wywoływanie istniejących API REST systemu HMIS: nagłówki uwierzytelniania, standardowa koperta odpowiedzi i indeks modułów dokumentacji.
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.
GPL-3.0, otwarta.
Co robi i kiedy
Opisuje wywoływanie istniejących API REST systemu HMIS: nagłówki uwierzytelniania, standardowa koperta odpowiedzi i indeks modułów dokumentacji.
Oryginalny opis (EN)
Reference for calling existing HMIS REST APIs. Use when consuming/invoking an HMIS endpoint — verifying data via API during issue investigation, writing a debug curl/script call, or checking an endpoint's request/response shape before writing a caller. Covers auth header conventions, the standard response envelope, and the developer_docs/api/using-apis/ module index. For building or extending an endpoint, use api-development instead.
Jak działa
- When This Applies
- Auth Headers
- Response Envelope
- Module Index
- Verifying Payments and Balances
- General Troubleshooting
Podgląd SKILL.md
---
name: api-usage
description: >
Reference for calling existing HMIS REST APIs. Use when consuming/invoking an HMIS endpoint —
verifying data via API during issue investigation, writing a debug curl/script call, or
checking an endpoint's request/response shape before writing a caller. Covers auth header
conventions, the standard response envelope, and the developer_docs/api/using-apis/ module
index. For building or extending an endpoint, use api-development instead.
user-invocable: true
---
# HMIS API Usage Guide
## When This Applies
Any time you need to **call** an HMIS REST endpoint that already exists — not create one:
- Verifying a bill/payment/balance via the read-only APIs while investigating an issue
- Writing a one-off curl/script call to check data during debugging
- Confirming an endpoint's request/response shape before writing a caller against it
- Wiring an API call into the in-app AI Chat tool-calling flow (`AnthropicApiService`)
If you're instead **building or extending** an endpoint (new `@Path` class or new method on one),
use the `api-development` skill — this one has no implementation detail.
---
## Auth Headers
Every request needs an auth header. Which one depends on the module — check the table below
before guessing:
| Header | Used by |
|---|---|
| `Finance` | Default for most modules (bills, balances, pharmacy, inward, users, etc.) |
| `Token` | Channel/booking appointments, consultant management |
| `Config` | Reading/updating `ConfigOption` application settings |
| `FHIR` | FHIR Patient resource endpoints |
| Custom (URL/JSON/Basic) | LIMS lab middleware |
| none | Membership scheme registration/payment (public) |
Send the key as the exact header name above, e.g. `Finance: <apiKey>`. A `401 Not a valid key`
response means the key is invalid, retired, or expired (`ApiKey.dateOfExpiary`).
## Response Envelope
Standard endpoints wrap responses the same way regardless of module:
```json
{"status":"success","code":200,"data":{...}}
{"status":"error","code":400,"message":"..."}
```
POST duplicate-detection endpoints return a bare (non-wrapped) shape instead:
```json
{"status":"already_exists","id":123,"name":"..."}
```
Always check `status` first, not just HTTP status code — some error conditions still return
HTTP 200 with `"status":"error"` in the body.
## Module Index
`developer_docs/api/using-apis/` has one self-contained reference file per module: base path,
auth header, request/response shapes, error codes. **Load only the file for the module you
need** — don't read the whole directory. Start from
[`developer_docs/api/using-apis/README.md`](../../../developer_docs/api/using-apis/README.md)
for the full, current table (module, file, auth header); it's kept up to date as new API docs
are added, so treat it as the source of truth rather than duplicating the list here.
If you're unsure which module owns the data you need, check `README.md`'s table first — several
files disambiguate related-sounding endpoints (e.g. `API_ADMISSION_DETAILS.md` is a consolidated
index of which admission-related API to call).
## Verifying Payments and Balances
A common task during issue investigation: confirm a bill's payments produced the correct balance
updates. Don't hand-roll this — follow
[`API_TESTING_WORKFLOWS.md`](../../../developer_docs/api/using-apis/API_TESTING_WORKFLOWS.md):
fetch the bill (`/api/costing_data/...`), pull the matching balance-history endpoint per payment
method (drawer/deposit/staff-welfare/agent), and assert `after == before + transactionValue`
(with float tolerance, since credit-company payments have no history endpoint and refunds/
cancellations use negative or reversing entries). This same file also covers batch verification
and common troubleshooting symptoms (case-sensitive bill numbers, empty `payments[]` on
transfer/issue bills, etc.).
## General Troubleshooting
| Symptom | Cause / Fix |
|---|---|
| `401 Not a valid key` | Auth key invalid, retired user, or expired — check `ApiKey.dateOfExpiary` |
| `404` / entity not found | IDs and bill numbers are often case-sensitive; confirm exact format |
| `200` with `"status":"error"` | Check `message`, not just HTTP status — see Response Envelope above |
| Numeric fields don't match exactly | Use tolerance (`abs(a - b) < 0.01`) for currency comparisons, not `==` |
Wersje
W bazie nie ma innych skilli o nazwie api-usage.
Migawka bazy z 13.11.2026 · wersja paczki 8b375e923596 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api-development
Prowadzi przez tworzenie i rozszerzanie endpointów REST w projekcie HMIS: struktura plików, uwierzytelnianie, format odpowiedzi, rejestracja, integracja z AnthropicApiService i lista kontrolna. - 100api-development
Prowadzi przez tworzenie i rozszerzanie endpointów REST w projekcie HMIS: struktura plików, uwierzytelnianie, format odpowiedzi, rejestracja, integracja z AnthropicApiService i lista kontrolna. - 100api-design
Projektuje API REST lub GraphQL z definicjami endpointów, schematami żądań i odpowiedzi, kodami błędów, wymaganiami uwierzytelniania i generowaniem OpenAPI. - 100wp-rest-api-development
Przegląda własne trasy REST API WordPressa: permission_callback, schemat odpowiedzi, uwierzytelnianie, wersjonowanie i kontrolery. - 100api-design
Definiuje kontrakty API REST i GraphQL: endpointy, schematy żądań i odpowiedzi, przepływy uwierzytelniania i strategię wersjonowania. - 100rest-endpoint-designer
Prawdopodobnie pomaga projektować endpointy REST i aktywuje się automatycznie przy frazach o rest endpoint designer w pracy nad API.