### Adding Examples to OpenAPI Operations

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Shows how to include examples for operation responses using the 'examples' property in OpenAPI.

```yaml
/enterprises/{enterpriseNumber}:
  get:
    operationId: getEnterprise
    parameters:
    - in: path
      name: enterpriseNumber
      required: true
      schema:
        type: string
    responses:
      "200":
        description: successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Enterprise'
            examples:
              success:
                description: Successful response with enterprise data
                value: {
                  "name": "Proximus",
                  "enterpriseNumber": "0202239951"
                }
```

--------------------------------

### Multi-valued Parameter Example Request

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates a GET request with a multi-valued query parameter for filtering car colors.

```http
GET /cars?color=black&color=blue
```

--------------------------------

### Query Parameter Examples

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Examples of common query parameters for filtering, pagination, and embedding resources.

```url
?page=3&pageSize=20
```

```url
?q=Belgacom
```

```url
?select=(name,address)
```

```url
?sort=age&sort=-name
```

```url
?embed=mainAddress
```

```url
?lang=fr
```

--------------------------------

### Cursor-based Pagination Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates cursor-based pagination, using a unique key ('afterCompany') to identify the starting point for the next page of results. This method is advantageous for high-volume collections.

```APIDOC
## GET /companies

### Description
Retrieves a paginated list of companies using cursor-based pagination.

### Method
GET

### Endpoint
/companies

### Query Parameters
- **afterCompany** (string) - REQUIRED (cursor-based) - The unique key of the last item from the previous page to retrieve subsequent items.
- **pageSize** (integer) - Optional - Maximum number of items per page. Must have a default value if absent.

### Response
#### Success Response (200)
- **self** (string) - hyperlink to the current page
- **items** (array) - List of items on the current page
  - **href** (string) - hyperlink to the item
  - **title** (string) - title of the item
- **pageSize** (integer) - Maximum number of items per page.
- **total** (integer) - Total number of items across all pages.
- **first** (string) - hyperlink to the first page
- **next** (string) - hyperlink to the next page, using the cursor of the last item in the current page.

### Request Example
```
GET https://api.socialsecurity.be/demo/v1/companies?afterCompany=0244640631 HTTP/1.1
```

### Response Example
```json
{
  "self": "/companies?afterCompany=0244640631&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "next": "/companies?afterCompany=0212165526&pageSize=2"
}
```
```

--------------------------------

### Cursor-based Pagination Request

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example GET request for retrieving items using cursor-based pagination. The 'afterCompany' parameter specifies the unique key to start retrieving items from.

```http
GET https://api.socialsecurity.be/demo/v1/companies?afterCompany=0244640631 HTTP/1.1

```

--------------------------------

### Controller examples for actions

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Controller resources are used for application-specific actions. POST is used for actions with side effects or requiring a request body. GET is used for idempotent actions without side effects.

```http
POST /accounts/123/withdraw
```

```http
POST /employers/93017373/sendNotification
```

```http
GET /convertMoney?from=EUR&amount=45&to=USD
```

--------------------------------

### Pagination Links Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Provides an example of pagination links for collections, using simple URI values for 'self', 'prev', and 'next' relations instead of the extensible link type.

```json
{
   "self": "/companies?page=2&pageSize=10",
   "prev": "/companies?page=1&pageSize=10",
   "next": "/companies?page=3&pageSize=10"
}
```

--------------------------------

### Example HTTP Request to Filter Companies

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This is an example HTTP GET request to the companies endpoint, filtering the results to include only those with the name 'belg'.

```http
GET https://api.socialsecurity.be/demo/v1/companies?name=belg HTTP/1.1

```

--------------------------------

### Example URI Extensions

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates the recommended practice of omitting file extensions from URIs, with a note on OpenAPI as an exception.

```text
GOOD: https://api.socialsecurity.be/demo/v1/socialSecretariats/331
BAD: https://api.socialsecurity.be/demo/v1/socialSecretariats/331.json
```

--------------------------------

### OpenAPI Media Type Specification

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of specifying media types for a GET operation in an OpenAPI 3.0 description.

```yaml
  /persons/{ssin}/photo:
    get:
      summary: Get the photo of the person

```

--------------------------------

### Example Multi-valued Query Parameter

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how to handle query parameters that can accept multiple values by repeating the parameter name.

```yaml
parameters:
- name: color
  in: query
  # defaults for style and explode properties are OK (style: form, explode: true)
  schema:
    type: array
    items:
      type: string
```

--------------------------------

### Reusable OpenAPI Document Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example shows a reusable OpenAPI document defining a 'Ssin' schema. It includes versioning information and an empty paths property, which is required for a valid OpenAPI document.

```yaml
openapi: "3.0.3"
info:
  title: person-identifier
  description: data types for person identifiers
  version: "1.1.2"
paths: {} # empty paths property required to be a valid OpenAPI document
components:
  schemas:
    Ssin:
      description: "Social Security Identification Number issued by the National Register or CBSS"
      type: string
      pattern: \d{11}
```

--------------------------------

### JSON Link Examples

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Examples of JSON properties representing links to other resources or pages.

```json
"next": "/companies?page=3&pageSize=2"
```

```json
"prev": "/companies?page=3&pageSize=2"
```

```json
"self": "/companies/202239951"
```

```json
"href": "/companies/202239951"
```

```json
"first": "https://api.socialsecurity.be/demo/v1/companies?pageSize=2"
```

```json
"last": "https://api.socialsecurity.be/demo/v1/companies?page=4&pageSize=2",
```

--------------------------------

### Offset-based Pagination Request

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example GET request for retrieving a specific page of items using offset-based pagination. Specify the desired page number and the number of items per page.

```http
GET https://api.socialsecurity.be/demo/v1/companies?page=2&pageSize=2 HTTP/1.1
```

--------------------------------

### OpenAPI Schema Description Example (GOOD)

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example shows the correct way to add descriptive information to an OpenAPI schema component using the 'description' property instead of 'title' for explanatory text.

```yaml
components:
  schemas:
    Pet:
      description: a pet in the pet store
      type: object
```

--------------------------------

### Example Query Parameters for Filtering

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Shows how to use query parameters to filter resource collections by search string, select specific properties, or specify language.

```text
https://api.socialsecurity.be/demo/v1/socialSecretariats?q=sdworx
https://api.socialsecurity.be/demo/v1/socialSecretariats/331?select=(name,address)
https://api.socialsecurity.be/demo/v1/socialSecretariats/331?lang=nl
```

--------------------------------

### Embedding Subresources Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how to embed subresources like 'children' and 'parents' in a GET request by using the 'embed' query parameter. The response includes an 'embedded' object containing the full JSON representation of the requested subresources.

```http
GET http://myrestapi/family/32456?embed=children&embed=parents
```

```json
{
  "self": "http://myrestapi/family/32456",
  "family": {
    "parents": [{
      "ssin": "12345678901",
      "href": "http://myrestapi/persons/12345678901"
    }],
    "children": [{
      "ssin": "98765432101",
      "href": "http://myrestapi/persons/98765432101"
    }]
  },
  "embedded": {
    "http://myrestapi/persons/12345678901": {
      "self": "http://myrestapi/persons/12345678901",
      "ssin": "12345678901",
      "givenName": "Jane",
      "lastName": "Doe"
    },
    "http://myrestapi/persons/98765432101": {
      "self": "http://myrestapi/persons/98765432101",
      "ssin": "98765432101",
      "givenName": "Bobby",
      "lastName": "Doe"
    }
  }
}
```

--------------------------------

### Example URI Notation

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates correct and incorrect URI structures for path segments and query parameters, emphasizing lowerCamelCase and avoiding trailing slashes.

```text
GOOD: https://api.socialsecurity.be/demo/v1/socialSecretariats/331
BAD: https://api.socialsecurity.be/demo/v1/Social_Secretariats/331
https://api.socialsecurity.be/demo/v1/social-secretariats/331

https://api.socialsecurity.be/demo/v1/socialSecretariats/331
BAD: https://api.socialsecurity.be/demo/v1/socialSecretariats/331/
https://api.socialsecurity.be/demo/v1/socialSecretariats?country=BE
BAD: https://api.socialsecurity.be/demo/v1/Social_Secretariats?Country=BE
```

--------------------------------

### JSON Property Naming: OK Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates correct JSON property naming conventions, using lowerCamelCase and American English, avoiding underscores and generic terms.

```json
"country": {
  "nisCode": 150,
  "isoCode": "BE",
  "name": "Belgium"
}
```

--------------------------------

### Bad Request Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example shows the structure of a 'Bad Request' response when the 'employerId' path parameter has an incorrect data format, such as non-numeric input.

```json
{
  "type": "urn:problem-type:belgif:badRequest",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
  "status": 400,
  "title": "Bad Request",
  "instance": "urn:uuid:d9e35127-e9b1-4201-a211-2b52e52508df",
  "detail": "The input message is incorrect",
  "issues": [
    {
      "type": "urn:problem-type:belgif:input-validation:schemaViolation",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/schemaViolation.html",
      "in": "path",
      "name": "employerId",
      "value": "abc",
      "detail": "This value should be numeric"
    }
  ]
}
```

--------------------------------

### Example JSON Response for Employer Classes

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This JSON structure represents a collection of employer classes, including their self-referential links and descriptions in Dutch and French. It also shows an example of a specific employer class with its value and descriptions.

```json
{
 "/appendices/employerclasses/1": {
  "self": "/appendices/employerclasses/1",
  "value": "1",
  "description": {
   "nl": "Bijzondere categorie voor werkgevers die voor hun arbeiders een speciale bijdrage verschuldigd zijn.",
   "fr": "Catégorie particulière pour les employeurs redevables pour les ouvriers d’une cotisation spéciale."
  }
 },
 "/appendices/employerclasses/0": {
  "self": "/appendices/employerclasses/0",
  "value": "0",
  "description": {
   "nl": "Algemene categorie voor werkgevers van commerciële of niet-commerciële aard.",
   "fr": "Catégorie générale pour les employeurs, de type commercial ou non-commercial."
  }
 }
}

```

--------------------------------

### Pagination Links Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates how simple URIs are used for pagination links within collections, corresponding to link relations like 'self', 'prev', and 'next'.

```APIDOC
### Pagination Links

#### Response Example
```json
{
   "self": "/companies?page=2&pageSize=10",
   "prev": "/companies?page=1&pageSize=10",
   "next": "/companies?page=3&pageSize=10"
}
```
```

--------------------------------

### Consult employer response example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

A successful response (200 OK) when consulting an employer resource, showing basic employer details.

```json
{
  "self": "/employers/93017373",
  "name": "Belgacom",
  "employerId": 93017373,
  "company": {
    "enterpriseNumber": "0202239951",
    "href": "/companies/202239951"
  }
}
```

--------------------------------

### Create New Resource Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example HTTP response for a successful resource creation (201 Created). Includes the 'Location' header pointing to the newly created resource.

```http
HTTP/1.1 201 Created
Location: /employers/93017373
Content-Length: 0
Date: Wed, 06 Jan 2016 15:37:16 GMT
```

--------------------------------

### Consulting a Collection of Employers

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example shows how to retrieve a list of employers from the API. The response includes links to individual employer resources and the total count.

```HTTP
GET https://api.socialsecurity.be/demo/v1/employers HTTP/1.1
```

```JSON
{
 "self": "https://api.socialsecurity.be/demo/v1/employers",
 "items":[
   {
     "href":"/employers/93017373",
     "title":"Belgacom",
     "employerId": 93017373,
     "enterpriseNumber": "0202239951"
   },
   {
     "href":"/employers/20620259",
     "title":"Partena VZW",
     "employerId": 20620259,
     "enterpriseNumber": "0409536968"
   }
 ],
 "total":2
}
```

--------------------------------

### Example POST Request for Enterprises

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This snippet shows a sample POST request to the /enterprises/{abc} endpoint, including enterprise details and board members with their periods.

```json
POST /enterprises/abc

{
  "name": "exampleEnterprise",
  "boardMembers": [
    {
      "ssin": "12345678901",
      "period": {
         "startDate": "2020-12-31",
         "endDate": "2020-01-01"
      }
    },
    {
      "ssin": "98765432109",
      "period": {
         "startDate": "2023-01-01",
         "endDate": "2024-01-01"
      }
    }
  ]
}
```

--------------------------------

### Document Resource Representation

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of a document resource representation within a collection, showing fields and identity key.

```json
{
  "ssin": "01234567890",
  "givenName": "John",
  "familyName": "Doe"
}
```

--------------------------------

### Resource Linking Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how to include self-referential links and links to other resources within a JSON response. The 'website' field is a direct URI and not a link to another API resource.

```json
{
   "self": "/companies/1"
   "owner": {
      "ssin": "12345678901",
      "href": "http://example.org/v1/persons/12345678901"
   },
   "website": "https://wwww.mycompany.com"
}
```

--------------------------------

### Consult employer with select response example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

A successful response when using the 'select' parameter to retrieve only the 'name' field of an employer.

```json
{
  "self": "/employers/93017373?select=(name)",
  "name": "Proximus"
}
```

--------------------------------

### Singleton Document Resource Representation

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of a singleton document resource representation, which is a fixed path segment and singular noun.

```json
{ "license": "Any information obtained from this API may not be made public, nor ..."}
```

--------------------------------

### API-Specific Problem Type Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates the structure of an API-specific problem type response, including type, href, status, title, detail, and instance.

```json
{
  "type": "urn:problem-type:cbss:socialStatus:searchCriteriaTooWide",
  "href": "https://api.ksz-bcss.fgov.be/socialStatus/v2/refData/problemTypes/urn:problem-type:cbss:socialStatus:searchCriteriaTooWide",
  "status": 400,
  "title": "Search criteria should be more specific",
  "detail": "Only one search parameter specified. Please specify at least two.",
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
}
```

--------------------------------

### Sensitive data handling examples

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how to handle sensitive data by moving it from URL parameters to the request payload, often using POST with a verb suffix.

```APIDOC
## POST /accounts/get

### Description
Retrieves account information. Sensitive data like email address is moved to the POST request body instead of being in the URL.

### Method
POST

### Endpoint
/accounts/get

### Parameters
#### Request Body
- **emailAddress** (string) - Required - The email address associated with the account.

## POST /accounts/update

### Description
Updates account information. Sensitive data like email address is moved to the POST request body.

### Method
POST

### Endpoint
/accounts/update

### Parameters
#### Request Body
- **emailAddress** (string) - Required - The email address associated with the account.
- **fieldsToUpdate** (object) - Required - An object containing the fields to update.

## POST /accounts/delete

### Description
Deletes an account. Sensitive data like email address is moved to the POST request body.

### Method
POST

### Endpoint
/accounts/delete

### Parameters
#### Request Body
- **emailAddress** (string) - Required - The email address associated with the account.

## POST /documents/query

### Description
Queries documents. Sensitive data like the creator's email address is moved to the POST request body.

### Method
POST

### Endpoint
/documents/query

### Parameters
#### Request Body
- **createdBy** (string) - Required - The email address of the document creator.

## POST /accounts/profilePictures

### Description
Uploads a profile picture for an account. The account identifier is part of the URL, not sensitive data in this context.

### Method
POST

### Endpoint
/accounts/profilePictures

### Parameters
#### Request Body
- **accountId** (string) - Required - The account ID.
- **pictureData** (string) - Required - The image data.

## POST /accounts/deactivate

### Description
Deactivates an account. The account identifier is part of the URL, not sensitive data in this context.

### Method
POST

### Endpoint
/accounts/deactivate

### Parameters
#### Request Body
- **accountId** (string) - Required - The account ID.
```

--------------------------------

### POST /enterprises/{enterpriseNumber}

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of a POST request to create or update enterprise information, and the corresponding 400 Bad Request response with detailed issues.

```APIDOC
## POST /enterprises/{enterpriseNumber}

### Description
This endpoint is used to create or update enterprise information. It can return a 400 Bad Request status if the input message is incorrect, providing details in the `issues` property.

### Method
POST

### Endpoint
/enterprises/{enterpriseNumber}

### Parameters
#### Path Parameters
- **enterpriseNumber** (string) - Required - The identifier for the enterprise.

#### Request Body
- **name** (string) - Required - The name of the enterprise.
- **boardMembers** (array) - Required - A list of board members.
  - **ssin** (string) - Required - Social Security Identification Number of the board member.
  - **period** (object) - Required - The period of service for the board member.
    - **startDate** (string) - Required - The start date of the period (YYYY-MM-DD).
    - **endDate** (string) - Required - The end date of the period (YYYY-MM-DD).

### Request Example
```json
{
  "name": "exampleEnterprise",
  "boardMembers": [
    {
      "ssin": "12345678901",
      "period": {
         "startDate": "2020-12-31",
         "endDate": "2020-01-01"
      }
    },
    {
      "ssin": "98765432109",
      "period": {
         "startDate": "2023-01-01",
         "endDate": "2024-01-01"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
(Not explicitly defined in the source, but typically would indicate successful creation or update)

#### Error Response (400 Bad Request)
- **type** (string) - Required - A URN identifying the problem type.
- **href** (string) - Optional - A link to further information about the problem.
- **title** (string) - Required - A short, human-readable summary of the problem.
- **status** (integer) - Required - The HTTP status code.
- **detail** (string) - Required - A human-readable explanation specific to this occurrence of the problem.
- **instance** (string) - Optional - A URN that identifies this specific occurrence of the problem.
- **issues** (array) - Optional - A list of specific issues found in the input.
  - **type** (string) - Required - A URN identifying the issue type.
  - **href** (string) - Optional - A link to further information about the issue.
  - **title** (string) - Required - A short, human-readable summary of the issue.
  - **detail** (string) - Required - A human-readable explanation specific to this occurrence of the issue.
  - **in** (string) - Required - The location of the invalid input (e.g., 'path', 'body', 'header', 'query').
  - **name** (string) - Required - The name of the invalid input field.
  - **value** (any) - Optional - The invalid value provided.
  - **replacedBy** (string) - Optional - Used when an SSIN has been replaced.

#### Response Example (400 Bad Request)
```json
{
  "type": "urn:problem-type:belgif:badRequest",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
  "title": "Bad Request",
  "status": 400,
  "detail": "The input message is incorrect",
  "instance": "urn:uuid:123456-1234-1235-4567489798",
  "issues": [
    {
      "type": "urn:problem-type:belgif:input-validation:schemaViolation",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/schemaViolation.html",
      "title": "Input isn\'t valid with respect to schema",
      "detail": "enterpriseNumber abc should be numeric",
      "in": "path",
      "name": "enterpriseNumber",
      "value": "abc"
    },
    {
      "type": "urn:problem-type:cbss:input-validation:replacedSsin",
      "href": "https://example.cbss.be/problems/replacedSsin",
      "title": "SSIN has been replaced. Use new SSIN.",
      "detail": "SSIN 12345678901 has been replaced by 23456789012",
      "in": "body",
      "name": "boardMembers[0].ssin",
      "value": "12345678901",
      "replacedBy": "23456789012"
    },
    {
      "type": "urn:problem-type:belgif:input-validation:referencedResourceNotFound",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/referencedResourceNotFound.html",
      "title": "Referenced resource not found",
      "detail": "Referenced resource boardMembers[1].ssin = '98765432109' does not exist",
      "in": "body",
      "name": "boardMembers[1].ssin",
      "value": "98765432109"
    },
    {
      "type": "urn:problem-type:belgif:input-validation:invalidInput",
      "href": "https://www.belgif.be/specification/rest/api-guide/issues/invalidInput.html",
      "title": "Invalid input",
      "detail": "endDate of a period should be after its startDate",
      "in": "body",
      "name": "boardMembers[0].period",
      "value": {
        "startDate": "2020-12-31",
        "endDate": "2020-01-01"
      }
    }
  ]
}
```
```

--------------------------------

### Consulting a Collection with Embedded Items

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example demonstrates how to request a collection of employer classes with their full representations embedded in the response. This is useful when collection items contain minimal data.

```HTTP
GET https://api.socialsecurity.be/demo/v1/appendices/employerclasses?embed=items HTTP/1.1

```

```JSON
{
 "self": "/appendices/employerclasses?embed=items",
 "items": [
  {
   "value": "0",
   "href": "/appendices/employerclasses/0"
  }, {
   "value": "2",
   "href": "/appendices/employerclasses/2"
  }
 ],
 "total":2,
 "embedded": {
   "/appendices/employerclasses/2": {
     "self": "/appendices/employerclasses/2",
     "value": "2",
     "description": {

```

--------------------------------

### Offset-based Pagination Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example JSON response for offset-based pagination. Includes links to the current, first, last, previous, and next pages, along with the items and pagination details.

```json
{
  "self": "/companies?page=2&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "page": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "last": "/companies?page=4&pageSize=2",
  "prev": "/companies?page=1&pageSize=2",
  "next": "/companies?page=3&pageSize=2"
}
```

--------------------------------

### Convert money between currencies

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Converts a specified amount of money from one currency to another. This is an example of an idempotent controller action without side effects, using the GET method.

```APIDOC
## GET /convertMoney

### Description
Converts a specified amount of money from one currency to another. This is an idempotent operation.

### Method
GET

### Endpoint
/convertMoney

### Parameters
#### Query Parameters
- **from** (string) - Required - The currency to convert from (e.g., EUR).
- **amount** (number) - Required - The amount of money to convert.
- **to** (string) - Required - The currency to convert to (e.g., USD).

### Response
#### Success Response (200)
- **convertedAmount** (number) - The converted amount in the target currency.
- **originalAmount** (number) - The original amount.
- **fromCurrency** (string) - The original currency.
- **toCurrency** (string) - The target currency.
```

--------------------------------

### Example Problem Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates a typical Problem Details response for a 'resource not found' error, including 'type', 'href', 'instance', 'status', 'title', 'detail', and custom 'issues' properties.

```json
{
  "type": "urn:problem-type:belgif:resourceNotFound",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
  "instance": "urn:uuid:d9e35127-e9b1-4201-a211-2b52e52508df",
  "status": 404,
  "title": "Resource is not found",
  "detail": "There is no enterprise in CBE with enterprise number 0206731645",
  "issues": [
      {
        "in": "path",
        "name": "enterpriseNumber",
        "detail": "the enterprise number is not assigned",
        "value": "0206731645"
      }
  ]
}

```

--------------------------------

### Query Parameters for Deep Subresource Embedding

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of a GET request to embed subresources nested more than one level deep, by specifying the path to the subresource within parentheses in the 'embed' query parameter.

```http
GET https://api.socialsecurity.be/demo/v1/employer/409536968?embed=employees(address)
```

--------------------------------

### Offset-based Pagination Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how to paginate through a collection using offset-based parameters like 'page' and 'pageSize'. The response includes navigation links and metadata about the current page and total items.

```APIDOC
## GET /companies

### Description
Retrieves a paginated list of companies.

### Method
GET

### Endpoint
/companies

### Query Parameters
- **page** (integer) - Required - The index of the page to be retrieved. Defaults to 1.
- **pageSize** (integer) - Optional - Maximum number of items per page. Must have a default value if absent.

### Response
#### Success Response (200)
- **self** (string) - hyperlink to the current page
- **items** (array) - List of items on the current page
  - **href** (string) - hyperlink to the item
  - **title** (string) - title of the item
- **pageSize** (integer) - Maximum number of items per page.
- **page** (integer) - index of the current page of items, 1-based.
- **total** (integer) - Total number of items across all pages.
- **first** (string) - hyperlink to the first page
- **last** (string) - hyperlink to the last page
- **prev** (string) - hyperlink to the previous page
- **next** (string) - hyperlink to the next page

### Request Example
```
GET https://api.socialsecurity.be/demo/v1/companies?page=2&pageSize=2 HTTP/1.1
```

### Response Example
```json
{
  "self": "/companies?page=2&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "page": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "last": "/companies?page=4&pageSize=2",
  "prev": "/companies?page=1&pageSize=2",
  "next": "/companies?page=3&pageSize=2"
}
```
```

--------------------------------

### Invalid `oneOf` Example JSON

Source: https://www.belgif.be/specification/rest/api-guide/index.html

An example JSON object that is invalid against the 'Agent' schema due to the overlapping definitions in its `oneOf` subschemas.

```json
{
  "ssin": "53480200724",
  "enterpriseNumber": "0123456789"
}
```

--------------------------------

### Path Parameter Naming Convention

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates the preferred lowerCamelCase notation for path parameters in OpenAPI.

```yaml
paths:
  /employers/{employerId}:
    # ....
```

--------------------------------

### Resource Update Example with Links

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Shows a PATCH request body where link-related fields like 'owner' can be updated. Fields not defined as links, like 'website', are treated as direct values.

```json
{
   "owner": {
      "ssin": "12345678902"
   },
   "website": "https://wwww.mynewwebsite.com"
}
```

--------------------------------

### OpenAPI Schema Title Override Example (BAD)

Source: https://www.belgif.be/specification/rest/api-guide/index.html

This example demonstrates an incorrect use of the 'title' property within an OpenAPI schema component. Using 'title' to override the schema name can lead to confusion in visualization tools.

```yaml
components:
  schemas:
    Pet:
      title: a pet in the pet store # title overrides the Pet schema name in visualization tooling
      type: object
```

--------------------------------

### Schema Naming Convention (OK vs KO)

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates the preferred UpperCamelCase naming convention for schema names in OpenAPI documents, contrasting with less desirable alternatives.

```text
KO | OK  
---|---
SSIN | Ssin  
CustomerInformation | Customer  
LanguageEnumeration | Language
```

--------------------------------

### Get all employers

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Retrieves a collection of employer documents. Supports filtering by employer name.

```APIDOC
## GET /employers

### Description
Retrieves all employer documents in the collection. This endpoint supports filtering based on the employer's name.

### Method
GET

### Endpoint
/employers

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter only employers that have a specific name.

### Request Example
```http
GET https://api.socialsecurity.be/demo/v1/companies?name=belg HTTP/1.1
```

### Response
#### Success Response (200)
- **self** (string) - The URI for the current request.
- **items** (array) - A list of employer objects, each containing an 'href' and 'title'.
  - **href** (string) - The URL to the specific employer resource.
  - **title** (string) - The name of the employer.
- **total** (integer) - The total number of employers matching the filter.

#### Response Example
```json
{
  "self": "/companies?name=belg",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    }, {
      "href": "/companies/448826918",
      "title": "Carrefour Belgium SA"
    }
  ],
  "total": 2
}
```

### Error Handling
- **400 Bad Request**: Generic error on client side, e.g., invalid request syntax.
- **404 Not Found**: The URI provided cannot be mapped to a resource.
- **200 OK**: Default response code, also when the filtered collection is empty.
```

--------------------------------

### Sending a notification to an employer

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Sends a notification to a specific employer. This is an example of a controller resource for performing application-specific actions.

```APIDOC
## POST /employers/{employerId}/sendNotification

### Description
Sends a notification to a specified employer.

### Method
POST

### Endpoint
/employers/{employerId}/sendNotification

### Parameters
#### Path Parameters
- **employerId** (string) - Required - The unique identifier of the employer.

### Request Example
```json
{
  "subject": "Important Update",
  "message": "Your account details have been updated."
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the notification was sent successfully.
```

--------------------------------

### Directory Structure for Documentation and Reference Data

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Illustrates the recommended directory structure for OpenAPI documentation and reference data resources within an API.

```text
 /
doc
     /openapi.json
     /openapi.yaml
     /<optional other documentation>
/refData
     /<list1OfCodes>
        /<code1>
        /<code2>
        /...
     /<list2OfCodes>
        /...
/<resource1>
     /...
/<resource2>
     /...
 ...
```

--------------------------------

### Expired Access Token Error Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of an HTTP 401 Unauthorized response when the provided access token has expired.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"

{
   "type": "urn:problem-type:belgif:expiredAccessToken",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/expiredAccessToken.html",
   "status": 401,
   "title": "Expired Access Token",
   "detail": "The Bearer access token found in the Authorization HTTP header has expired"
}
```

--------------------------------

### Invalid Access Token Error Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of an HTTP 401 Unauthorized response when an invalid access token is provided.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token is invalid"

{
   "type": "urn:problem-type:belgif:invalidAccessToken",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/invalidAccessToken.html",
   "status": 401,
   "title": "Invalid Access Token",
   "detail": "The Bearer access token found in the Authorization HTTP header is invalid"
}
```

--------------------------------

### No Access Token Error Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of an HTTP 401 Unauthorized response when no access token is provided in the Authorization header.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="example"

{
   "type": "urn:problem-type:belgif:noAccessToken",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/noAccessToken.html",
   "status": 401,
   "title": "No Access Token",
   "detail": "No Bearer access token found in Authorization HTTP header"
}
```

--------------------------------

### Reusable OpenAPI Document Structure

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Outlines the recommended directory structure for organizing reusable OpenAPI documents across multiple APIs.

```text
<domain>/<version>/<domain-version>.yaml
<domain>/<subdomain>/<version>/<domain-subdomain-version>.yaml
```

--------------------------------

### Withdrawal from an account

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Performs a withdrawal from a specified account. This is an example of a controller resource used for actions that cannot be mapped to standard CRUD operations.

```APIDOC
## POST /accounts/{accountId}/withdraw

### Description
Initiates a withdrawal from a specific account. This operation has side effects and modifies the account state.

### Method
POST

### Endpoint
/accounts/{accountId}/withdraw

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The unique identifier of the account.

### Request Example
```json
{
  "amount": 100,
  "currency": "USD"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of the withdrawal.

#### Error Response (400)
- **error** (string) - Details about the withdrawal failure (e.g., insufficient funds).
```

--------------------------------

### Language Negotiation with Accept-Language Header

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how a client can request a preferred language for API responses using the Accept-Language header. The server responds with the content in the negotiated language.

```HTTP
Accept-Language: nl-BE, nl;q=0.9, fr-BE;q=0.8, fr;q=0.7, en;q=0.6, *;q=0.5

GET /countries/BE
```

```HTTP
Content-Language: nl

{
  "code": "BE",
  "name": "België"
}
```

--------------------------------

### Missing Scope Error Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of an HTTP 403 Forbidden response when the access token lacks the required scope for the requested operation.

```http
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="example", error="insufficient_scope", error_description="Missing scope to perform request", scope="enterprise-read"
{
   "type": "urn:problem-type:belgif:missingScope",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/missingScope.html",
   "status": 403,
   "title": "Missing Scope",
   "detail": "Forbidden to consult the enterprise resource",
   "requiredScopes": ["enterprise-read"]
}
```

--------------------------------

### Custom Format Identifier OpenAPI Schema

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Schema for a custom string identifier. This example uses a pattern for short, easily encoded identifiers.

```yaml
type: string
pattern: "^[a-z0-9]{1-20}$"
```

--------------------------------

### POST - Create a new resource

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Used for resource creation. The request body contains the suggested state representation of the new resource. The response includes a Location header with the URI of the newly created resource and its representation in the body.

```APIDOC
## POST

### Description
Creates a new resource in a server-owned collection.

### Method
POST

### Endpoint
[Collection URI]

### Request Body
- **representation** (object) - Required - The suggested state of the new resource.

### Response
#### Success Response (201 Created)
- **Location** (string) - The URI of the newly created resource.
- **body** (object) - Optional - The representation of the created resource.

#### Success Response (200 OK)
- **body** (object) - Optional - The representation of the created resource or controller info.

#### Success Response (202 Accepted)
- **body** (object) - Optional - Controller info.
```

--------------------------------

### HEAD - Retrieve response headers

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Used to retrieve only the HTTP response headers for a resource. It returns the same headers as a GET request but with an empty body.

```APIDOC
## HEAD

### Description
Retrieves the HTTP response headers for a resource without returning the body.

### Method
HEAD

### Endpoint
[Resource URI]

### Response
#### Success Response (200 OK)
- Returns the headers equivalent to a GET request.
```

--------------------------------

### Cursor-based Pagination Response

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example JSON response for cursor-based pagination. Includes a link to the next page based on the cursor, along with items and pagination details. Note the absence of 'page' and 'prev' properties.

```json
{
  "self": "/companies?afterCompany=0244640631&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "next": "/companies?afterCompany=0212165526&pageSize=2"
}
```

--------------------------------

### Resource Links Example

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Demonstrates how links are used to reference other resources or provide a self-link within a resource representation. The `self` attribute provides the resource's own location, while `href` links to related resources.

```APIDOC
## GET https://api.socialsecurity.be/demo/v1/companies/1

### Description
Retrieves a company resource including its self-link and a link to its owner.

### Method
GET

### Endpoint
/companies/1

### Response
#### Success Response (200)
- **self** (string) - Absolute URI to the resource's own location.
- **owner** (object) - Link to the owner resource.
  - **ssin** (string) - The Social Security Number of the owner.
  - **href** (string) - Absolute URI to the owner resource.
- **website** (string) - The company's website URI.

#### Response Example
```json
{
   "self": "/companies/1",
   "owner": {
      "ssin": "12345678901",
      "href": "http://example.org/v1/persons/12345678901"
   },
   "website": "https://wwww.mycompany.com"
}
```

## PATCH https://api.socialsecurity.be/demo/v1/companies/1

### Description
Updates a company resource, potentially including its owner's SSIN and website.

### Method
PATCH

### Endpoint
/companies/1

### Request Body
- **owner** (object) - Object containing updated owner information.
  - **ssin** (string) - The new Social Security Number of the owner.
- **website** (string) - The new website URI for the company.

### Request Example
```json
{
   "owner": {
      "ssin": "12345678902"
   },
   "website": "https://wwww.mynewwebsite.com"
}
```
```

--------------------------------

### Required Properties Declaration (GOOD)

Source: https://www.belgif.be/specification/rest/api-guide/index.html

Example of correctly declaring a property as required in an OpenAPI schema. The property must be declared in both `properties` and `required` lists.

```yaml
type: object
properties:
  givenName:
    type: string
required: [givenName]
```