API reference
API reference
These examples explain request headers, response formats and error handling. They are illustrative patterns, not a published production API contract. Use the specification supplied for your agreed integration.
Authentication
Make authenticated requests from your server. Keep credentials in environment variables or a secrets manager, and follow the authentication scheme supplied for your integration.
Authorization: Bearer YOUR_API_KEY
Accept: application/jsonNever place a secret key in browser JavaScript, a public repository or a support ticket.
List services
Example requestA simple read request demonstrates the shape of a service catalogue response. The available services and fields depend on your connection.
/v1/servicesService cataloguecurl "https://api.example.com/v1/services" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Accept: application/json"const response = await fetch("https://api.example.com/v1/services", {
headers: {
Authorization: `Bearer ${process.env.HPG_API_KEY}`,
Accept: "application/json",
},
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
const services = await response.json();import os
import requests
response = requests.get(
"https://api.example.com/v1/services",
headers={"Authorization": f"Bearer {os.environ['HPG_API_KEY']}"},
timeout=30,
)
response.raise_for_status()
services = response.json()Response object
Read the response as JSON and validate the fields your application depends on. Here’s a small sample of a catalogue object.
{
"data": [
{
"id": "service_example",
"name": "Example healthcare service",
"type": "consultation"
}
]
}| Field | Type | Description |
|---|---|---|
data | array | A list of service objects. |
data[].id | string | A service identifier. |
data[].name | string | A human-readable service name. |
data[].type | string | The service category. |
Handling errors
Check the response status before processing the body. Keep useful diagnostic details in your server logs and show customers a clear, actionable message.
| Status | Meaning | Next step |
|---|---|---|
200 | OK | Process the successful response. |
400 | Bad request | Check required fields and request formatting. |
401 | Unauthorised | Review credentials and authentication headers. |
429 | Rate limited | Respect retry guidance from the endpoint. |
5xx | Server error | Follow the agreed retry and escalation policy. |
Confirm endpoint-specific status codes, limits and retry rules in your integration specification.