Introduction
This document provides an overview of how to interact with a GraphQL endpoint, including authentication, basic queries, filtering, pagination, and search.
Authentication
Most APIs will need to secure access to certain types of data depending on who requested it, and GraphQL is no different. GraphQL execution should begin after authentication middleware confirms the user’s identity and passes that information to the GraphQL layer.
Setting the API Key The API key is typically passed in the Authorization header of the request. Ensure your API key is active and has the required permissions.
Making a Request
curl -X POST http://localhost:9090/graphql `
-H "Content-Type: application/json" `
-H "BLIKSUND-X-API-KEY: dccadfea-45a2-407e-bcfd-bda1ad9684ca" `
-d '{
"query": "query { resources { callsign resource_id sk_resource station station_id } }"
}'
- Noted: Please make sure Curl installed before executing the command above.
Querying Data
Query for All Data
Use case: This supports the use case when we want to fetch all data.
- All Resources
query MyQuery {
resources {
callsign
resource_id
sk_resource
station
station_id
}
}
- All Patients
query MyQuery {
patients {
age
date_of_birth
gender
sk_patient
weight
}
}
Use case: This supports the use case when we want to fetch distinct all data by field names.
This case can be used to fetch data to be presented to dropdown boxes as parameters for reporting purposes
- All Oxygens
query MyQuery {
oxygens(distinct_fields: ["route"]) {
route
}
}
Use case: Be able to present the number of records that is grouped in under each distinct value in a column.
- The distinct_values query retrieves distinct values from specified columns, filtered by a date range and logical conditions.
Query: Distinct Values
This document explains how to use the distinct_values query, including its parameters and expected response.
Query Syntax
query MyQuery {
distinct_values(
columns: ["station"],
end_date: "2025-01-13",
start_date: "2022-05-18",
use_or: false
) {
column
value
}
}
Parameters
-
columns(Required):
A list of column names from which to fetch distinct values.
Example:["station"]. -
start_date(Required):
The start date for filtering data. Records on or after this date are included.
Format:YYYY-MM-DD. -
end_date(Required):
The end date for filtering data. Records on or before this date are included.
Format:YYYY-MM-DD. -
use_or(Optional, Default:false):
Determines the logical condition when multiple columns are provided:true: Returns records matching any column criteria (logical OR).false: Returns records matching all column criteria (logical AND).
Fields Returned
column: The name of the column.value: The distinct value from the column.
Example Response
{
"data": {
"distinct_values": [
{
"column": "station",
"value": "Bliksund"
},
{
"column": "station",
"value": "Helse Vest"
},
{
"column": "station",
"value": "UI Test Station"
}
]
}
}
This response shows the distinct values for the "station" column within the specified date range.
Notes
- Ensure the date range (
start_dateandend_date) is valid and includes the desired data. - The query supports filtering multiple columns, but the
use_orparameter determines how the conditions are combined. - If no data matches the filters, the response will return an empty array for
distinct_values.
Query: Distinct Values with Filters
Query Syntax
query MyQuery {
distinct_values(
columns: ["station"]
end_date: "2025-01-13"
start_date: "2020-05-18"
use_or: false
filters: [
{ column: "degree_of_urgency", value: "V", operator: EQUALS },
{ column: "distance", value: "10", operator: GREATER_THAN_OR_EQUAL }
]
) {
column
value
}
}
Parameters
-
columns(Required):
A list of column names from which to fetch distinct values.
Example:["station"]. -
start_date(Required):
The start date for filtering data. Records on or after this date are included.
Format:YYYY-MM-DD. -
end_date(Required):
The end date for filtering data. Records on or before this date are included.
Format:YYYY-MM-DD. -
use_or(Optional, Default:false):
Determines the logical condition when multiple filters are provided:true: Returns records matching any filter (logical OR).false: Returns records matching all filters (logical AND).
Filters Parameter
The filters parameter allows you to add custom filtering conditions.
It accepts a list of filter objects, each with the following attributes:
-
column(Required):
The name of the column to apply the filter on.
Example:"degree_of_urgency". -
value(Required):
The value to compare against.
Example:"V"or"10". -
operator(Required):
The comparison operator to use for the filter. Supported operators include:EQUALS: Match exactly.GREATER_THAN: Value is greater than the specified value.LESS_THAN: Value is less than the specified value.GREATER_THAN_OR_EQUAL: Value is greater than or equal to the specified value.LESS_THAN_OR_EQUAL: Value is less than or equal to the specified value.
Query Breakdown
- Retrieve distinct values from the
"station"column. - Filter records by a date range:
- Start Date:
"2020-05-18" - End Date:
"2025-01-13"
- Start Date:
- Apply the following filters:
"degree_of_urgency"must equal"V"."distance"must be greater than or equal to"10".
- Use logical AND (
use_or: false) to ensure all filter conditions are satisfied.
Fields Returned
column: The name of the column.value: The distinct value from the column.
Example Response
{
"data": {
"distinct_values": [
{ "column": "station", "value": "Station A" },
{ "column": "station", "value": "Station B" }
]
}
}
This response shows the distinct values for the "station" column that satisfy the filters and date range.
Notes
- Date Range: Ensure that the
start_dateandend_dateare correctly formatted and represent the desired range. - Logical Conditions: Use
use_orto switch between logical AND (false) and OR (true). - Filters: The
filtersparameter allows combining multiple conditions, enabling complex queries.
Query: Unique Counts with Filters
Query Syntax
query MyQuery {
unique_counts(
columns: ["station"]
end_date: "2025-01-13"
use_or: false
filters: [
{ column: "station", value: "Bliksund", operator: EQUALS },
{ column: "degree_of_urgency", value: "V", operator: EQUALS }
]
start_date: "2020-05-18"
) {
column
count
value
}
}
Parameters
-
columns(Required):
Specifies the columns for which unique counts will be calculated.
Example:["station"]. -
start_date(Required):
Filters data to include records on or after this date.
Format:YYYY-MM-DD. -
end_date(Required):
Filters data to include records on or before this date.
Format:YYYY-MM-DD. -
use_or(Optional, Default:false):
Defines the logical condition between filters:true: Records satisfying any filter are included (logical OR).false: Records satisfying all filters are included (logical AND).
Filters Parameter
The filters parameter specifies conditions to refine the query.
Each filter object includes:
-
column(Required):
The column to apply the filter.
Example:"station"or"degree_of_urgency". -
value(Required):
The value to filter on.
Example:"Bliksund"or"V". -
operator(Required):
Specifies the comparison operator for the filter. Supported operators:EQUALS: Value matches exactly.GREATER_THAN: Value is greater than the specified value.LESS_THAN: Value is less than the specified value.GREATER_THAN_OR_EQUAL: Value is greater than or equal to the specified value.LESS_THAN_OR_EQUAL: Value is less than or equal to the specified value.
Query Breakdown
- Unique Counts for Column: Calculate unique counts for the
"station"column. - Date Range: Records between
"2020-05-18"and"2025-01-13". - Filters:
"station"must equal"Bliksund"."degree_of_urgency"must equal"V".
- Logical Condition: Use logical AND (
use_or: false) to enforce all filter conditions.
Fields Returned
column: The column name for which unique counts were calculated.count: The count of unique values in the column that meet the criteria.value: The unique value in the column.
Example Response
{
"data": {
"unique_counts": [
{
"column": "station",
"count": 22,
"value": "Bliksund"
}
]
}
}
This response indicates that there are 5 unique records for the "station" column with the value "Bliksund" that match the filters and date range.
Notes
- Date Filters: Ensure that the date range is correct and includes the data of interest.
- Logical Filters: Use
use_or: trueto allow broader filtering when multiple conditions are applied. - Filter Customization: Combine various columns and operators to tailor the query to specific needs.
- Results: The query returns a list of unique values in the specified column, along with their respective counts.
Query: Station Resources
This document explains how to use the station_resources query to retrieve information about stations and their associated resources.
Query Syntax
query MyQuery {
station_resources {
resources {
resource_id
}
station_id
station_name
}
}
Description
The station_resources query retrieves data about stations, including their unique identifiers, names, and the resources associated with each station.
Fields Returned
Root Fields
station_resources: A list of stations with their associated data.
Nested Fields
-
station_id(String):
The unique identifier for each station. -
station_name(String):
The name of the station. -
resources(Array):
A list of resources associated with the station. Each resource object contains:resource_id(String): The unique identifier for the resource.
Example Response
{
"data": {
"station_resources": [
{
"resources": [
{
"resource_id": 108
},
{
"resource_id": 89
},
{
"resource_id": 97
},
{
"resource_id": 89
},
{
"resource_id": 99
},
{
"resource_id": 98
},
{
"resource_id": 100
},
{
"resource_id": 105
},
{
"resource_id": 104
},
{
"resource_id": 106
},
{
"resource_id": 101
},
{
"resource_id": 89
},
{
"resource_id": 97
},
{
"resource_id": 103
},
{
"resource_id": 97
},
{
"resource_id": 102
}
],
"station_id": 12,
"station_name": "Bliksund Academy"
},
{
"resources": [
{
"resource_id": 112
},
{
"resource_id": 290
},
{
"resource_id": 54
},
{
"resource_id": 112
},
{
"resource_id": 56
},
{
"resource_id": 54
}
],
"station_id": 5,
"station_name": "<I>UI Test Station"
},
{
"resources": [
{
"resource_id": 40
},
{
"resource_id": 120
},
{
"resource_id": 43
},
{
"resource_id": 44
},
{
"resource_id": 116
},
{
"resource_id": 39
},
{
"resource_id": 57
},
{
"resource_id": 40
},
{
"resource_id": 43
},
{
"resource_id": 114
},
{
"resource_id": 45
},
{
"resource_id": 308
},
{
"resource_id": 110
},
{
"resource_id": 57
},
{
"resource_id": 41
},
{
"resource_id": 61
},
{
"resource_id": 62
},
{
"resource_id": 71
},
{
"resource_id": 88
},
{
"resource_id": 61
},
{
"resource_id": 45
},
{
"resource_id": 71
},
{
"resource_id": 39
},
{
"resource_id": 109
},
{
"resource_id": 53
},
{
"resource_id": 45
},
{
"resource_id": 1
},
{
"resource_id": 46
},
{
"resource_id": 126
},
{
"resource_id": 43
},
{
"resource_id": 302
},
{
"resource_id": 44
},
{
"resource_id": 88
},
{
"resource_id": 315
},
{
"resource_id": 59
},
{
"resource_id": 42
},
{
"resource_id": 51
},
{
"resource_id": 45
},
{
"resource_id": 36
},
{
"resource_id": 37
},
{
"resource_id": 115
},
{
"resource_id": 51
},
{
"resource_id": 42
},
{
"resource_id": 1
},
{
"resource_id": 295
},
{
"resource_id": 46
}
],
"station_id": 1,
"station_name": "Bliksund"
},
{
"resources": [
{
"resource_id": 219
}
],
"station_id": 54,
"station_name": "Larvik Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 65
},
{
"resource_id": 66
},
{
"resource_id": 63
},
{
"resource_id": 70
},
{
"resource_id": 81
},
{
"resource_id": 69
}
],
"station_id": 6,
"station_name": "Helse Nord"
},
{
"resources": [
{
"resource_id": 21
},
{
"resource_id": 22
},
{
"resource_id": 19
},
{
"resource_id": 15
},
{
"resource_id": 23
}
],
"station_id": 4,
"station_name": "Helse Midt-Norge"
},
{
"resources": [
{
"resource_id": 192
},
{
"resource_id": 191
}
],
"station_id": 44,
"station_name": "Oppdal Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 152
},
{
"resource_id": 153
}
],
"station_id": 32,
"station_name": "Fana Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 179
}
],
"station_id": 41,
"station_name": "Ålesund Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 216
},
{
"resource_id": 215
}
],
"station_id": 53,
"station_name": "Sandefjord Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 234
}
],
"station_id": 59,
"station_name": "Bykle Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 169
}
],
"station_id": 37,
"station_name": "Eidfjord Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 31
},
{
"resource_id": 48
},
{
"resource_id": 90
},
{
"resource_id": 32
},
{
"resource_id": 47
},
{
"resource_id": 94
},
{
"resource_id": 96
},
{
"resource_id": 75
},
{
"resource_id": 74
},
{
"resource_id": 49
},
{
"resource_id": 95
},
{
"resource_id": 50
}
],
"station_id": 3,
"station_name": "Helse Vest"
},
{
"resources": [
{
"resource_id": 311
}
],
"station_id": 86,
"station_name": "Grimstad Test Lab"
},
{
"resources": [
{
"resource_id": 92
}
],
"station_id": 14,
"station_name": "Test"
},
{
"resources": [
{
"resource_id": 93
},
{
"resource_id": 5
},
{
"resource_id": 3
},
{
"resource_id": 2
}
],
"station_id": 2,
"station_name": "Helse Sør-Øst"
},
{
"resources": [
{
"resource_id": 207
},
{
"resource_id": 209
},
{
"resource_id": 208
}
],
"station_id": 51,
"station_name": "Horten Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 154
}
],
"station_id": 33,
"station_name": "Godvik Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 264
}
],
"station_id": 69,
"station_name": "Bærum Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 293
}
],
"station_id": 70,
"station_name": "Luftambulansen Arendal"
},
{
"resources": [
{
"resource_id": 170
}
],
"station_id": 38,
"station_name": "Førde Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 200
}
],
"station_id": 48,
"station_name": "Steinkjer Ambulansestasjon"
},
{
"resources": [
{
"resource_id": 210
}
],
"station_id": 52,
"station_name": "Tønsberg Ambulansestasjon"
}
]
}
}
Explanation of Response
Central Stationhas two resources:"R001"and"R002".North Stationhas one resource:"R003".
Use Case Scenarios
-
Resource Management:
Retrieve the resources available at each station for operational planning. -
Station Overview:
Get a list of all stations with their names and associated resources. -
Data Linking:
Use thestation_idto link additional station details or perform further queries.
Notes
- If a station has no resources, the
resourcesarray will be empty. - Ensure that the response size is manageable if querying a large number of stations.
Query: Records Count
This document explains how to use the records_count query to retrieve the total count of records for a specific station or for all stations when no station is specified.
Query Syntax
query MyQuery {
records_count(station: "Bliksund") {
count
}
}
Description
The records_count query retrieves the total count of records based on the specified station parameter. This parameter can be:
nullor empty: Returns the total count of records for all stations.- A specific value: Filters records and returns the count for the specified station.
Query Parameters
station(Optional):
The name of the station for which to retrieve the count.- If
nullor not provided, counts all records across all stations. - If specified, counts only the records associated with the given station.
Example:"Bliksund".
- If
Fields Returned
count(Integer):
The total number of records that match the query criteria.
Example Queries and Responses
1. Records for a Specific Station
Query
query MyQuery {
records_count(station: "Bliksund") {
count
}
}
Response
{
"data": {
"records_count": {
"count": 120
}
}
}
Explanation: There are 120 records associated with the "Bliksund" station.
2. Records for All Stations
Query
query MyQuery {
records_count(station: null) {
count
}
}
OR
query MyQuery {
records_count {
count
}
}
Response
{
"data": {
"records_count": {
"count": 5000
}
}
}
Explanation: There are 5,000 records across all stations.
Use Case Scenarios
-
Station-specific Reporting:
Retrieve the number of records for a single station (e.g.,"Bliksund"). -
Global Reporting:
Get the total number of records when no station is specified. -
Dynamic Filtering:
Use a parameterized station value to allow flexibility in querying specific or all stations.
Notes
- If the
stationparameter is omitted or set tonull, the query returns the count of all records. - Ensure the station name provided is valid to avoid returning a count of zero.
- This query is useful for dashboards and analytics to display station-specific or overall record counts.