ZorgAPIs API (0.5.0)

Download OpenAPI specification:Download

Definition of the API Library for Dutch Healthcare (ZorgAPIs) API.

This specification is maintained on GitHub.

Introduction

ZorgAPIs API enables the creation of applications that can interact with the API Library for Dutch Healthcare, such as retrieving API requirements, creating and managing organizations and API specifications, or publishing declarations of conformity.

This specification is part of the ZorgAPIs Developer Portal. Utilize our sandbox API to ensure your integrations are seamless and robust before publishing data to the production environment.

Users

Users API

Get user information for authenticated user

Returns a single user.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "id": "2aa3349c-dfa6-4308-b562-f7fc8be6c053",
  • "name": "John Doe",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

User invitations

User invitations API

List all user invitations

Returns a list of user invitations.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
emailAddress string asc ?sort=asc(emailAddress)
desc ?sort=desc(emailAddress)
responseTime date-time asc ?sort=asc(responseTime)
desc ?sort=desc(responseTime)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=desc(createTime)

This causes results to be sorted by createTime in descending order (from most recent to oldest).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
organizationId uuid eq ?filter=eq(organizationId,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(organizationId,"533d3fe3-bccc-405a-9904-4f516e892856")
emailAddress string eq ?filter=eq(emailAddress,"john.doe@nictiz.nl")
neq ?filter=neq(emailAddress,"john.doe@nictiz.nl")
has ?filter=has(emailAddress,"john")
stw ?filter=stw(emailAddress,"john")
enw ?filter=enw(emailAddress,"nictiz.nl")
reg ?filter=reg(emailAddress,"^[a-zA-Z0-9 ]+$")
status InvitationStatus eq ?filter=eq(status,"PENDING")
neq ?filter=neq(status,"PENDING")
responseTime date-time eq ?filter=eq(responseTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(responseTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(responseTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(responseTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(responseTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(responseTime,"2024-03-16T14:15:30.500Z")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a user invitation by ID

Returns a single user invitation.

Authorizations:
oauth2
path Parameters
invitationId
required
string <uuid>
Examples: 30ca5cc5-b84c-4993-b15b-8ab182dab89c

The ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "organizationId": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "organization": {
    },
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "ACCEPTED",
  • "responseTime": "2024-03-11T00:00:00.000Z",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Accept a pending user invitation

Accept a pending user invitation.

Authorizations:
oauth2
path Parameters
invitationId
required
string <uuid>
Examples: 30ca5cc5-b84c-4993-b15b-8ab182dab89c

The ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "organizationId": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "organization": {
    },
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "ACCEPTED",
  • "responseTime": "2024-03-11T00:00:00.000Z",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Decline a pending user invitation

Decline a pending user invitation.

Authorizations:
oauth2
path Parameters
invitationId
required
string <uuid>
Examples: 30ca5cc5-b84c-4993-b15b-8ab182dab89c

The ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "organizationId": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "organization": {
    },
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "DECLINED",
  • "responseTime": "2024-03-11T00:00:00.000Z",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

User memberships

User memberships API

List all user memberships

Returns a list of user memberships.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=desc(createTime)

This causes results to be sorted by createTime in descending order (from most recent to oldest).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
organizationId uuid eq ?filter=eq(organizationId,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(organizationId,"533d3fe3-bccc-405a-9904-4f516e892856")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a user membership by ID

Returns a single user membership.

Authorizations:
oauth2
path Parameters
membershipId
required
string <uuid>
Examples: cefdc28f-550d-4005-9ca7-c1836202c37b

The ID of the membership

Responses

Response samples

Content type
application/json
{
  • "id": "cefdc28f-550d-4005-9ca7-c1836202c37b",
  • "organizationId": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "organization": {
    },
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Delete a user membership

Deletes a single user membership.

Authorizations:
oauth2
path Parameters
membershipId
required
string <uuid>
Examples: cefdc28f-550d-4005-9ca7-c1836202c37b

The ID of the membership

Responses

Response samples

Content type
application/json
{
  • "status": 400,
  • "type": "INVALID_ARGUMENT",
  • "message": "Failed to parse body"
}

Organizations

Organizations API

List all organizations

Returns a list of organizations.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
name string asc ?sort=asc(name)
desc ?sort=desc(name)
address.city string asc ?sort=asc(address.city)
desc ?sort=desc(address.city)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=asc(name)

This causes the results to be sorted by name in ascending order (from A to Z).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
name string eq ?filter=eq(name,"Nictiz")
neq ?filter=neq(name,"Nictiz")
has ?filter=has(name,"Nic")
stw ?filter=stw(name,"Nic")
enw ?filter=enw(name,"tiz")
reg ?filter=reg(name,"^[a-zA-Z0-9 ]+$")
address.street string eq ?filter=eq(address.street,"Oude Middenweg")
neq ?filter=neq(address.street,"Oude Middenweg")
has ?filter=has(address.street,"Oude")
stw ?filter=stw(address.street,"Oude")
enw ?filter=enw(address.street,"Middenweg")
reg ?filter=reg(address.street,"^[a-zA-Z ]+$")
address.postalCode string eq ?filter=eq(address.postalCode,"2491 AC")
neq ?filter=neq(address.postalCode,"2491 AC")
has ?filter=has(address.postalCode,"2491")
stw ?filter=stw(address.postalCode,"2491")
enw ?filter=enw(address.postalCode,"AC")
reg ?filter=reg(address.postalCode,"^(\d{4})\s*([A-Z]{2})$")
address.city string eq ?filter=eq(address.city,"The Hague")
neq ?filter=neq(address.city,"The Hague")
has ?filter=has(address.city,"The")
stw ?filter=stw(address.city,"The")
enw ?filter=enw(address.city,"Hague")
reg ?filter=reg(address.city,"^[a-zA-Z ]+$")
address.country Country eq ?filter=eq(address.country,"NL")
neq ?filter=neq(address.country,"NL")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an organization

Adds an organization to the collection.

Authorizations:
oauth2
Request Body schema: application/json

Organization object to add

name
required
string <= 255 characters

The name of the organization

description
string or null <= 1000 characters

The description of the organization

website
string or null <= 1000 characters

The URL of the organization's website

githubUrl
string or null <= 1000 characters

The URL of the organization on GitHub

gitlabUrl
string or null <= 1000 characters

The URL of the organization on GitLab

emailAddress
required
string <email> <= 254 characters

The email address of the organization

phoneNumber
string or null <= 50 characters

The phone number of the organization

object or null (Address)

The address information

Responses

Request samples

Content type
application/json
{
  • "name": "Nictiz",
  • "description": "Nictiz is the Dutch competence center for electronic exchange of health and care information.",
  • "website": "https://nictiz.nl/",
  • "emailAddress": "info@nictiz.nl",
  • "phoneNumber": "+31 (0)70 317 3450",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "name": "Nictiz",
  • "description": "Nictiz is the Dutch competence center for electronic exchange of health and care information.",
  • "website": "https://nictiz.nl/",
  • "emailAddress": "info@nictiz.nl",
  • "phoneNumber": "+31 (0)70 317 3450",
  • "address": {
    },
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Get an organization by ID

Returns a single organization.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

Responses

Response samples

Content type
application/json
{
  • "id": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "name": "Nictiz",
  • "description": "Nictiz is the Dutch competence center for electronic exchange of health and care information.",
  • "website": "https://nictiz.nl/",
  • "emailAddress": "info@nictiz.nl",
  • "phoneNumber": "+31 (0)70 317 3450",
  • "address": {
    },
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Update an organization

Updates a single organization.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

Request Body schema: application/json

Updated organization object

name
required
string <= 255 characters

The name of the organization

description
string or null <= 1000 characters

The description of the organization

website
string or null <= 1000 characters

The URL of the organization's website

githubUrl
string or null <= 1000 characters

The URL of the organization on GitHub

gitlabUrl
string or null <= 1000 characters

The URL of the organization on GitLab

emailAddress
required
string <email> <= 254 characters

The email address of the organization

phoneNumber
string or null <= 50 characters

The phone number of the organization

object or null (Address)

The address information

Responses

Request samples

Content type
application/json
{
  • "name": "Nictiz",
  • "description": "Nictiz is the Dutch competence center for electronic exchange of health and care information.",
  • "website": "https://nictiz.nl/",
  • "emailAddress": "info@nictiz.nl",
  • "phoneNumber": "+31 (0)70 317 3450",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "b9b95cd7-8d6e-4c91-8861-854828cf1730",
  • "name": "Nictiz",
  • "description": "Nictiz is the Dutch competence center for electronic exchange of health and care information.",
  • "website": "https://nictiz.nl/",
  • "emailAddress": "info@nictiz.nl",
  • "phoneNumber": "+31 (0)70 317 3450",
  • "address": {
    },
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Organization invitations

Organization invitations API

List all organization invitations

Returns a list of organization invitations.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
emailAddress string asc ?sort=asc(emailAddress)
desc ?sort=desc(emailAddress)
responseTime date-time asc ?sort=asc(responseTime)
desc ?sort=desc(responseTime)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=desc(createTime)

This causes results to be sorted by createTime in descending order (from most recent to oldest).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
emailAddress string eq ?filter=eq(emailAddress,"john.doe@nictiz.nl")
neq ?filter=neq(emailAddress,"john.doe@nictiz.nl")
has ?filter=has(emailAddress,"john")
stw ?filter=stw(emailAddress,"john")
enw ?filter=enw(emailAddress,"nictiz.nl")
reg ?filter=reg(emailAddress,"^[a-zA-Z0-9 ]+$")
status InvitationStatus eq ?filter=eq(status,"PENDING")
neq ?filter=neq(status,"PENDING")
userId uuid eq ?filter=eq(userId,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(userId,"533d3fe3-bccc-405a-9904-4f516e892856")
responseTime date-time eq ?filter=eq(responseTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(responseTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(responseTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(responseTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(responseTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(responseTime,"2024-03-16T14:15:30.500Z")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an organization invitation

Adds an organization invitation to the collection.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

Request Body schema: application/json

Organization invitation object to add

emailAddress
required
string <email> <= 254 characters

The email address of the user being invited

Responses

Request samples

Content type
application/json
{
  • "emailAddress": "john.doe@nictiz.nl"
}

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "PENDING",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Get an organization invitation by ID

Returns a single organization invitation.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

invitationId
required
string <uuid>
Examples: 30ca5cc5-b84c-4993-b15b-8ab182dab89c

The ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "ACCEPTED",
  • "userId": "7375d2bf-884c-4adf-86f5-5b35f0da864b",
  • "user": {
    },
  • "responseTime": "2024-03-11T00:00:00.000Z",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Cancel a pending organization invitation

Cancel a pending organization invitation.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

invitationId
required
string <uuid>
Examples: 30ca5cc5-b84c-4993-b15b-8ab182dab89c

The ID of the invitation

Responses

Response samples

Content type
application/json
{
  • "id": "30ca5cc5-b84c-4993-b15b-8ab182dab89c",
  • "emailAddress": "john.doe@nictiz.nl",
  • "status": "CANCELED",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Organization memberships

Organization memberships API

List all organization memberships

Returns a list of organization memberships.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=desc(createTime)

This causes results to be sorted by createTime in descending order (from most recent to oldest).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
userId uuid eq ?filter=eq(userId,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(userId,"533d3fe3-bccc-405a-9904-4f516e892856")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an organization membership by ID

Returns a single organization membership.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

membershipId
required
string <uuid>
Examples: cefdc28f-550d-4005-9ca7-c1836202c37b

The ID of the membership

Responses

Response samples

Content type
application/json
{
  • "id": "cefdc28f-550d-4005-9ca7-c1836202c37b",
  • "userId": "7375d2bf-884c-4adf-86f5-5b35f0da864b",
  • "user": {
    },
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Delete an organization membership

Deletes a single organization membership.

Authorizations:
oauth2
path Parameters
organizationId
required
string <uuid>
Examples: b9b95cd7-8d6e-4c91-8861-854828cf1730

The ID of the organization

membershipId
required
string <uuid>
Examples: cefdc28f-550d-4005-9ca7-c1836202c37b

The ID of the membership

Responses

Response samples

Content type
application/json
{
  • "status": 400,
  • "type": "INVALID_ARGUMENT",
  • "message": "Failed to parse body"
}

API requirements versions

API requirements versions API

List all API requirements versions

Returns a list of API requirements versions.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
name string asc ?sort=asc(name)
desc ?sort=desc(name)
publishTime date-time asc ?sort=asc(publishTime)
desc ?sort=desc(publishTime)
semVer.major integer asc ?sort=asc(semVer.major)
desc ?sort=desc(semVer.major)
semVer.minor integer asc ?sort=asc(semVer.minor)
desc ?sort=desc(semVer.minor)
semVer.patch integer asc ?sort=asc(semVer.patch)
desc ?sort=desc(semVer.patch)
semVer.preRelease string asc ?sort=asc(semVer.preRelease)
desc ?sort=desc(semVer.preRelease)
semVer.build string asc ?sort=asc(semVer.build)
desc ?sort=desc(semVer.build)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=desc(publishTime)

This causes results to be sorted by publishTime in descending order (from most recent to oldest).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
name string eq ?filter=eq(name,"1.2.0")
neq ?filter=neq(name,"1.2.0")
has ?filter=has(name,"1.2")
stw ?filter=stw(name,"1.2")
enw ?filter=enw(name,"2.0")
reg ?filter=reg(name,"^[a-zA-Z0-9 ]+$")
publishTime date-time eq ?filter=eq(publishTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(publishTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(publishTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(publishTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(publishTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(publishTime,"2024-03-16T14:15:30.500Z")
semVer.major integer eq ?filter=eq(semVer.major,1)
neq ?filter=neq(semVer.major,1)
gt ?filter=gt(semVer.major,1)
gte ?filter=gte(semVer.major,1)
lt ?filter=lt(semVer.major,1)
lte ?filter=lte(semVer.major,1)
semVer.minor integer eq ?filter=eq(semVer.minor,2)
neq ?filter=neq(semVer.minor,2)
gt ?filter=gt(semVer.minor,2)
gte ?filter=gte(semVer.minor,2)
lt ?filter=lt(semVer.minor,2)
lte ?filter=lte(semVer.minor,2)
semVer.patch integer eq ?filter=eq(semVer.patch,0)
neq ?filter=neq(semVer.patch,0)
gt ?filter=gt(semVer.patch,0)
gte ?filter=gte(semVer.patch,0)
lt ?filter=lt(semVer.patch,0)
lte ?filter=lte(semVer.patch,0)
semVer.preRelease string eq ?filter=eq(semVer.preRelease,"beta")
neq ?filter=neq(semVer.preRelease,"beta")
has ?filter=has(semVer.preRelease,"be")
stw ?filter=stw(semVer.preRelease,"be")
enw ?filter=enw(semVer.preRelease,"ta")
reg ?filter=reg(semVer.preRelease,"^[a-zA-Z0-9 ]+$")
semVer.build string eq ?filter=eq(semVer.build,"exp.sha.5114f85")
neq ?filter=neq(semVer.build,"exp.sha.5114f85")
has ?filter=has(semVer.build,"exp.sha")
stw ?filter=stw(semVer.build,"exp.sha")
enw ?filter=enw(semVer.build,"5114f85")
reg ?filter=reg(semVer.build,"^[a-zA-Z0-9 ]+$")
lifecycleState ProductLifecycleState eq ?filter=eq(lifecycleState,"PUBLISHED")
neq ?filter=neq(lifecycleState,"PUBLISHED")
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")
Authorizations:
oauth2
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an API requirements version

Adds an API requirements version to the collection.

Authorizations:
oauth2
Request Body schema: application/json

API requirements version object to add

name
required
string <= 255 characters

The name of the API requirements version

description
required
string or null <= 1000 characters

The description of the API requirements version

url
required
string <= 1000 characters

The URL of the API requirements version documentation

publishTime
required
string <date-time>

The date and time at which the API requirements version was published

required
object

The Semantic Versioning Specification (SemVer) version information

lifecycleState
required
string
Enum: "DRAFT" "PUBLISHED" "DEPRECATED" "RETIRED"

The lifecycle state of the API requirements version

required
Array of objects (ApiRequirement)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "29c4913a-5ca1-4e91-8353-48866eb6093e",
  • "name": "1.2.0",
  • "description": "This specification sets out requirements for Application Programming Interfaces (APIs) in Dutch Healthcare. It has been developed as part of the Nictiz API strategy.",
  • "publishTime": "2023-07-12T10:45:30.500Z",
  • "semVer": {
    },
  • "lifecycleState": "PUBLISHED",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Get an API requirements version by name

Returns a single API requirements version.

Authorizations:
oauth2
path Parameters
versionName
required
string
Examples: 1.2.0

The name of the version

Responses

Response samples

Content type
application/json
{
  • "id": "29c4913a-5ca1-4e91-8353-48866eb6093e",
  • "name": "1.2.0",
  • "description": "This specification sets out requirements for Application Programming Interfaces (APIs) in Dutch Healthcare. It has been developed as part of the Nictiz API strategy.",
  • "publishTime": "2023-07-12T10:45:30.500Z",
  • "semVer": {
    },
  • "lifecycleState": "PUBLISHED",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

Update an API requirements version

Updates a single API requirements version.

Authorizations:
oauth2
path Parameters
versionName
required
string
Examples: 1.2.0

The name of the version

Request Body schema: application/json

Updated API requirements version object

name
required
string <= 255 characters

The name of the API requirements version

description
required
string or null <= 1000 characters

The description of the API requirements version

url
required
string <= 1000 characters

The URL of the API requirements version documentation

publishTime
required
string <date-time>

The date and time at which the API requirements version was published

required
object

The Semantic Versioning Specification (SemVer) version information

lifecycleState
required
string
Enum: "DRAFT" "PUBLISHED" "DEPRECATED" "RETIRED"

The lifecycle state of the API requirements version

Responses

Request samples

Content type
application/json
{
  • "name": "1.2.0",
  • "description": "This specification sets out requirements for Application Programming Interfaces (APIs) in Dutch Healthcare. It has been developed as part of the Nictiz API strategy.",
  • "publishTime": "2023-07-12T10:45:30.500Z",
  • "semVer": {
    },
  • "lifecycleState": "PUBLISHED"
}

Response samples

Content type
application/json
{
  • "id": "29c4913a-5ca1-4e91-8353-48866eb6093e",
  • "name": "1.2.0",
  • "description": "This specification sets out requirements for Application Programming Interfaces (APIs) in Dutch Healthcare. It has been developed as part of the Nictiz API strategy.",
  • "publishTime": "2023-07-12T10:45:30.500Z",
  • "semVer": {
    },
  • "lifecycleState": "PUBLISHED",
  • "createTime": "2023-10-24T14:15:30.500Z",
  • "createdByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "createdByUser": {
    },
  • "updateTime": "2023-10-25T10:45:30.500Z",
  • "updatedByUserId": "533d3fe3-bccc-405a-9904-4f516e892856",
  • "updatedByUser": {
    }
}

API requirements version API requirements

API requirements version API requirements API

List all API requirements version API requirements

Returns a list of API requirements.

Details

Sort expressions

The following table lists the field names and directions you can use in a sort expression.

Field Type Direction Example
id uuid asc ?sort=asc(id)
desc ?sort=desc(id)
code string asc ?sort=asc(code)
desc ?sort=desc(code)
category ApiRequirementCategory asc ?sort=asc(category)
desc ?sort=desc(category)
createTime date-time asc ?sort=asc(createTime)
desc ?sort=desc(createTime)
updateTime date-time asc ?sort=asc(updateTime)
desc ?sort=desc(updateTime)

Default sort expression

If the sort parameter is omitted, the default sort expression is used:

?sort=asc(code)

This causes results to be sorted by code in ascending order (from A to Z).

Filter expressions

The following table lists the field names and operators you can use in a filter expression.

Field Type Operator Example
id uuid eq ?filter=eq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
neq ?filter=neq(id,"533d3fe3-bccc-405a-9904-4f516e892856")
code string eq ?filter=eq(code,"SD001")
neq ?filter=neq(code,"SD001")
has ?filter=has(code,"SD0")
stw ?filter=stw(code,"SD0")
enw ?filter=enw(code,"001")
reg ?filter=reg(code,"^[a-zA-Z0-9 ]+$")
description string eq ?filter=eq(description,"The description")
neq ?filter=neq(description,"The description")
has ?filter=has(description,"The")
stw ?filter=stw(description,"The")
enw ?filter=enw(description,"description")
reg ?filter=reg(description,"^[a-zA-Z0-9 ]+$")
requirementLevel RequirementLevel eq ?filter=eq(requirementLevel,"MUST")
neq ?filter=neq(requirementLevel,"MUST")
score integer eq ?filter=eq(score,1)
neq ?filter=neq(score,1)
gt ?filter=gt(score,1)
gte ?filter=gte(score,1)
lt ?filter=lt(score,1)
lte ?filter=lte(score,1)
category ApiRequirementCategory eq ?filter=eq(category,"API_SPECIFICATION_AND_DOCUMENTATION")
neq ?filter=neq(category,"API_SPECIFICATION_AND_DOCUMENTATION")
roles.$it ApiRole eq ?filter=any(roles,eq($it,"API_SPECIFIER"))
neq ?filter=all(roles,neq($it,"API_SPECIFIER"))
perspectiveTypes.$it ApiPerspectiveType eq ?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))
neq ?filter=all(perspectiveTypes,neq($it,"API_SPECIFICATION"))
architecturalStyles.$it ApiArchitecturalStyle eq ?filter=any(architecturalStyles,eq($it,"REST"))
neq ?filter=all(architecturalStyles,neq($it,"REST"))
standardizationLevels.$it ApiStandardizationLevel eq ?filter=any(standardizationLevels,eq($it,"OPEN_API"))
neq ?filter=all(standardizationLevels,neq($it,"OPEN_API"))
createTime date-time eq ?filter=eq(createTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(createTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(createTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(createTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(createTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(createTime,"2024-03-16T14:15:30.500Z")
updateTime date-time eq ?filter=eq(updateTime,"2024-03-16T14:15:30.500Z")
neq ?filter=neq(updateTime,"2024-03-16T14:15:30.500Z")
gt ?filter=gt(updateTime,"2024-03-16T14:15:30.500Z")
gte ?filter=gte(updateTime,"2024-03-16T14:15:30.500Z")
lt ?filter=lt(updateTime,"2024-03-16T14:15:30.500Z")
lte ?filter=lte(updateTime,"2024-03-16T14:15:30.500Z")

Examples

All API_SPECIFICATION REST requirements

?filter=and(any(perspectiveTypes,eq($it,"API_SPECIFICATION")),any(architecturalStyles,eq($it,"REST")))
Authorizations:
oauth2
path Parameters
versionName
required
string
Examples: 1.2.0

The name of the version

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100
Examples: limit=100

The limit query string parameter restricts the number of items to return at one time.

Details
  • Minimum is 0
  • Maximum is 100
skip
integer <int32> >= 0
Default: 0
Examples: skip=0

The skip query string parameter defines the number of items to skip before returning items.

Details
  • Minimum is 0
sort
string
Default: ""
Examples:
  • sort= - Empty
  • sort=asc(createTime) - Create time (ascending)
  • sort=asc(name),desc(createTime) - Combined sort
  • sort=asc(user.name) - Nested field

The sort query string parameter sorts the data returned from your request.

Details

Sort syntax

A single sort expression uses the form:

direction(field)

In this syntax:

  • direction - The sort direction to use
  • field - The name of the field to sort by
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])

Sort directions

  • asc - Ascending (smallest to largest)
    • e.g. 1 to 100, A to Z, oldest to newest, false to true, not null to null
  • desc - Descending (largest to smallest)
    • e.g. 100 to 1, Z to A, newest to oldest, true to false, null to not null

Functions

Sort functionality can be expanded using functions. These functions help to sort specific data types. For example, they allow to sort on the year component of a date-time type field.

Functions can be applied to the field component of a sort expression, like so:

direction(function(field))

Sort functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Combining sort expressions

Sort expressions can be combined using a comma (,).

Sort expressions are evaluated from left to right, for example:

?sort=asc(name),asc(createTime)

Causes the results to be sorted first by name in ascending order (from A to Z), and then by createTime in ascending order (from oldest to newest).

filter
string
Default: ""
Examples:
  • filter= - Empty
  • filter=stw(name,"Nictiz") - Starts with
  • filter=or(eq(name,"Nictiz"),eq(name,"MedMij")) - Name equals (OR)
  • filter=and(eq(year(createTime),2023),eq(month(createTime),10)) - Created in October 2023

The filter query string parameter restricts the data returned from your request.

Details

Filter syntax

A single filter expression uses the form:

operator(field,value)

In this syntax:

  • operator - The type of filter to use
  • field - The name of the field to filter on
    • Nested fields can be referenced using dot notation (field.nested) or bracket notation (field["nested"])
  • value - The value that the field must be evaluated against

Filter operators

Operator Description Field type Example
eq Equal to value boolean eq(field,true)
number eq(field,1234)
string eq(field,"text")
date-time eq(field,"2024-03-16T14:15:30.500Z")
uuid eq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null eq(field,null)
neq Not equal to value boolean neq(field,true)
number neq(field,1234)
string neq(field,"text")
date-time neq(field,"2024-03-16T14:15:30.500Z")
uuid neq(field,"533d3fe3-bccc-405a-9904-4f516e892856")
null neq(field,null)
gt Greater than value number gt(field,1234)
date-time gt(field,"2024-03-16T14:15:30.500Z")
gte Greater than or equal to value number gte(field,1234)
date-time gte(field,"2024-03-16T14:15:30.500Z")
lt Less than value number lt(field,1234)
date-time lt(field,"2024-03-16T14:15:30.500Z")
lte Less than or equal to value number lte(field,1234)
date-time lte(field,"2024-03-16T14:15:30.500Z")
has Contains substring string has(field,"text")
stw Starts with string string stw(field,"text")
enw Ends with string string enw(field,"text")
reg Matches regular expression string reg(field,"^[a-zA-Z0-9 ]+$")

List operators

The any and all operators can be used to filter on list fields. These operators will filter the data returned to only include results where any or all items in given list return true for given filter expression.

A single list operator uses the form:

listOperator(listField,operator($it,value))

In this syntax:

  • listOperator - The list operator to use
    • The any operator returns true if the filter expression is true for at least one item in the list
    • The all operator returns true if the filter expression is true for every item in the list
  • listField - The name of the list field to filter on
  • operator - The type of filter to use on the list items
  • $it - Keyword that refers to each individual item of the list field
    • If the item is an object, you can reference nested fields like so: $it.nestedField
  • value - The value that the list item must be evaluated against

The operator in a list operator can be seen as a lambda function, where it represents the body of a loop in a programming language with $it representing the current item of the list during iteration.

Examples

Any perspectiveType that is equal to "API_SPECIFICATION":

?filter=any(perspectiveTypes,eq($it,"API_SPECIFICATION"))

All versions have any url with a type that is equal to "FUNCTIONAL_DESIGN":

?filter=all(versions,any($it.urls,eq($it.type,"FUNCTIONAL_DESIGN")))

not operator

The not operator evaluates to true if its sub-expression evaluates to false, and vice-versa.

It can be applied to any filter operator, like so:

not(operator(field,value))

Filter values

There are a couple of important rules for filter values:

  • URL-reserved characters - Characters such as & must be url-encoded in the usual way.
  • Value syntax - Value syntax is similar to that of JSON:
    • string - Must be written with double quotes (for example: "value")
      • date-time - Must be written as string
      • enum - Must be written as string
      • uuid - Must be written as string
    • number - Must be written as JSON number
    • boolean - Must be written as JSON boolean: either true or false
    • null - Must be written as JSON null literal
  • Regular expressions - You can also use regular expressions in filter values using the reg operator. The syntax uses POSIX regular expressions (similar to Perl) and have these additional rules:
    • Case sensitivity - Regular expression matching is case-sensitive.
  • Date-time values - For date-time values, use ISO 8601 format (for example: "2024-03-16T14:15:30.500Z").

Functions

Filter functionality can be expanded using functions. These functions help to filter specific data types. For example, they allow to filter on the year component of a date-time type field.

Functions can be applied to the field component of a filter expression, like so:

operator(function(field),value) 

Filter functions

Function Description Input type Output type Example input Example output
year Returns the year component of a date value date-time integer year("2024-03-16T14:15:30.500Z") 2024
month Returns the month component of a date value date-time integer month("2024-03-16T14:15:30.500Z") 3
day Returns the day of the month component of a date value date-time integer day("2024-03-16T14:15:30.500Z") 16
hour Returns the hour component of a datetime value date-time integer hour("2024-03-16T14:15:30.500Z") 14
minute Returns the minute component of a datetime value date-time integer minute("2024-03-16T14:15:30.500Z") 15
second Returns the second component of a datetime value date-time integer second("2024-03-16T14:15:30.500Z") 30
millisecond Returns the millisecond component of a datetime value date-time integer millisecond("2024-03-16T14:15:30.500Z") 500
floor Rounds a number down to the nearest integer float integer floor(25.75) 25
double
ceiling Rounds a number up to the nearest integer float integer ceiling(25.75) 26
double
round Rounds a number to the nearest integer float integer round(25.75) 26
double
lower Converts a string to lowercase string string lower("Nictiz") "nictiz"
upper Converts a string to uppercase string string upper("Nictiz") "NICTIZ"

Examples

Date is in the month of March:

?filter=eq(month(dateField),3)

Combining filter expressions

Filter expressions can be combined using the or and and operators.

Examples

Name is either ("Nictiz" OR "MedMij"):

?filter=or(eq(name,"Nictiz"),eq(name,"MedMij"))

Name does NOT end with "Mij":

?filter=not(enw(name,"Mij"))
count
boolean
Default: false

The count query string parameter defines whether to provide a count of the total number of results.

Details

To request a count, use:

?count=true

The count will be returned in the Total-Count header, for example:

200 OK
Total-Count: 78

Note that when the filter query string parameter is set, the total number of results returned in the Total-Count header reflects the filtered result set.

Responses