Reserved words
A list of reserved words exists for common used practices
Query parameters
| Term | Description | Example | Ref |
|---|---|---|---|
| page | When a collection resources is paged, use this parameter to request a specific page. Page numbers are 1-based. | ?page=3&pageSize=20 | ??? |
| pageSize | When a collection resources is paged, use this parameter to specify the page size. | ?page=3&pageSize=20 | ??? |
| q | The standard search parameter to do a full-text search. | ?q=Belgacom | ??? |
| select | Filter the resource properties to the ones specified. | ?select=(name,address) | ??? |
| sort | Multi-value query param with list of properties to sort on. | ||
| Default sorting direction is ascending. To indicate descending direction, the property may be prefixed with -. | ?sort=age&sort=-name | ??? | |
| embed | Request to embed subresource | ?embed=mainAddress | [???](#Embedding resources) |
| lang | language to filter multi-language descriptions | ?lang=fr | [???](#Multi-language descriptions) |
JSON properties
| Term | Description | Example | Ref |
|---|---|---|---|
next | The next-reference contains the absolute URL of the next page in a paged collection result. | | |
prev | The previous-reference contains the absolute URL of the previous page in a paged collection result. | | |
self | The self-reference contains the absolute URL of the resource itself. | | |
href | A reference (absolute URL) to another resource. | | |
first | A reference (absolute URL) to the first page in a paged collection result. | | |
last | A reference (absolute URL) to the last page in a paged collection result. | | |
items | an array with the items of a collection result. | ||
total | the total number of items in a collection result, after filtering. | ||
page | the index of a page in a paged collection result | ||
pageSize | the maximum number of items in a page of a paged collection result. | ||
embedded | a map of embedded subresources, with URIs as property key and the resource as value |
HTTP headers
This list includes all standardized and common non-standard HTTP headers.
Custom HTTP headers SHOULD be prefixed with the organization’s name.
Custom headers that are standardized across Belgian Government organizations use the BelGov- prefix.
X- headers were initially reserved for non-standardized parameters, but the usage of X- headers is deprecated (RFC-6648).
Instead, it is recommended that company specific header’ names should incorporate the organization’s name.
However, for backwards compatibility reasons, headers with the X- prefix may still be used.
| HTTP Header | Type | Description | Reference |
|---|---|---|---|
| Location | Response | Used in redirection, or when a new resource has been created. | [???](#Create a new resource), ???, status codes 301, 303 and 307 |
| Accept | Request | Media type(s) that is(/are) acceptable for the response. | [???](#Media Types) |
| Content-Type | Request/Response | The Media type of the body of the request. | [???](#Media Types) |
| X-HTTP-Method-Override | Request | Override the method specified in the request. | ??? |
| Retry-After | Response | Suggest amount of time for the client to wait before retrying the request when temporarily unavailable or quota reached | [???](#Service Unavailable), [???](#Too Many Requests), [???](#Too Many Failed Requests) |
| Allow | Response | Valid methods for a specified resource. | ??? |
| ETag | Request | Identifier for returned response content | [???](#Conditional requests) |
| If-None-Match | Response | Return resource if ETag changed | [???](#Conditional requests) |
| Last-Modified | Request | Time on which resource was last modified | [???](#Conditional requests) |
| If-Modified-Since | Response | Return resource only if changed since specified timestamp | [???](#Conditional requests) |
| Vary | Response | Specifies which request headers change response content | [???](#Client caching directives) |
| Cache-Control | Response | Indicates HTTP client how to cache responses | [???](#Client caching directives) |
Standard HTTP Headers referenced in the style guide
| HTTP Header | Type | Description | Reference |
|---|---|---|---|
| Company-Trace-Id | Request/Response | Unique ID for tracing purposes, identifying the request or response | ??? |
| Company-Related-Trace-Id | Response | BelGov-Trace-Id value used on related request | ??? |
Resource names
| path | Description | Reference |
|---|---|---|
| /docs | Browseable API documentation UI | |
| /openapi.json | API documentation (swagger file and other) | ??? |
| /refData | resources representing reference data used in the API (i.e. code lists) | ??? |
| /health | API health status | ??? |
| /metrics | Metric responses |