CBSS REST APIs aim to follow the Belgif REST Guidelines. This document describes any CBSS-specific additions or exceptions to these standard guidelines. It can be used as an addendum to the technical specifications of each CBSS REST API.

1. General Activity Diagram

The activity diagram below illustrates the business logic that generally applies to all CBSS REST APIs.

Diagram

2. API contracts

2.1. OpenAPI

CBSS API contracts are defined in the OpenAPI 3.0 Specification standard format. The contracts are provided as a zip archive with a folder structure that may contain multiple YAML files, wherein common types (such as the standard types from Belgif) are referenced using relative paths. By convention, the main root specification file is called openapi.yaml.

CBSS REST API contract folder structure
📒 <api-name>-openapi-<major>.<minor>.zip
  📂 belgif (1)
    📂 common
      📁 v1
        📄 common-v1.yaml
    📂 problem
      📁 v1
        📄 problem-v1.yaml
  📂 cbss (2)
    📂 common
      📁 v1
        📄 common-v1.yaml
  📄 openapi.yaml (3)
1 Belgif common types
2 CBSS common types
3 Root API specification file
Click to view an example openapi.yaml specification file for a fictional CBSS API called "Pet Store" 
openapi: 3.0.3
info:
  title: petStore (1)
  description: Pet Store API
    <details> (2)
      <summary>changelog</summary>
      * 2023-09-01: Initial version
      * 2023-09-12:
        - An item in the API changelog
        - Another item in the API changelog
    </details>
  version: "1.1" (3)
  contact:
    name: KSZ/BCSS Service Desk
    email: servicedesk@ksz-bcss.fgov.be (4)
servers:
  - url: /petStore/v1 (5)
    description: https://api[.test|.acpt].ksz-bcss.fgov.be/petStore/v1
externalDocs:
  url: https://[TBD].ksz-bcss.fgov.be/petStore/v1/cookbook.html (6)
  description: Pet Store API Cookbook
tags: (7)
  - name: Pets
  - name: Monitoring
paths:
  /health:
    $ref: cbss/common/v1/common-v1.yaml#/paths/~1health (8)
  /pets:
    get:
      ...
      tags:
        - Pets
      security:
        - oauth-socsec:
            - scope:cbss:api:petStore:consult
  ...
components:
  schemas:
    ...
  securitySchemes: (9)
    oauth-socsec:
      type: oauth2
      description: access using access token retrieved from oauth2 server
      flows:
        clientCredentials:
          tokenUrl: https://placeholder.socialsecurity.be/oauth2endpoint
          scopes:
            scope:cbss:api:monitoring: access to health check operation
            scope:cbss:api:petStore:consult: consult CBSS Pet Store API
security:
  - oauth-socsec:
      - scope:cbss:api:monitoring
      - scope:cbss:api:petStore:consult
1 API name in lowerCamelCase, corresponds to the first segment of the API base path
2 API changelog rendered as a collapsible element in SwaggerUI
3 The major.minor version of the API
4 The service desk is the single point of contact for any (production) issues
5 Relative API base path: /<apiName>/v<major>
6 Link to the published cookbook (in progress: exact URL yet to be defined)
7 Tags that are used for grouping related operations
8 Generic /health resource referenced from CBSS common-v1.yaml
9 See Security

2.2. Cookbook

CBSS strives to document the API as much as possible within the OpenAPI contract itself. Service documentation that can’t be specified in the OpenAPI contract, is published in a "Cookbook".

2.3. Client annex

A cookbook "annex" per client contains client-specific documentation, like the authorized legal contexts, their scopes and their client integration checks (NL / FR). Potential specific configurations or unauthorized properties are also mentioned.

3. Security

CBSS APIs are secured via OAuth2 protocol by using the client credentials flow for authentication. Client applications should request an access token from the tokenUrl by providing their credentials. The obtained access token grants access to the CBSS API with the configured scope(s) for that client.

3.1. Scopes

A scope represents a permission to access one or more operations. Scopes for CBSS API operations follow this naming convention:
scope:cbss:api:<apiName>:<permission-within-api-in-hyphen-case> e.g. scope:cbss:api:petStore:consult.

Additionally, a single api-wide generic scope is used for accessing the /health path: scope:cbss:api:monitoring (see Monitoring).

4. Authorization

In addition to the scopes as mentioned in the security section, the client should also pass the legal context when a making a CBSS API call.

CBSS APIs accept a Legal-Context HTTP header, indicating the business purpose for which a request is made, as specified in the authorization granted by the sectoral committee.

4.2. Authorization Configuration

The authorization of a client for a CBSS API operation is configured on the legal context and the scope level. A legal context gives access to one or more scopes. Consequently, a legal context gives access to the set of API operations defined by the scope to which it has access. That way, the authorization for a service can be seen theoretically as such:

client
|1..* legal context
      | 1..* scope
             | 1..* operation

The client annex mentions per legal context:

  • the scopes for which the client has access.

  • the operations linked to the scope

  • the specific parameters or filters applicable for the operation in this legal context

CBSS verifies that the client uses an authorized combination of legal context and scope(s) for the called API path, otherwise an Unauthorized Legal Context problem is returned.

5. Trace IDs

CBSS APIs support the BelGov-Trace-Id and BelGov-Related-Trace-Id HTTP headers, as specified in the Belgif REST Guide even though they’re not specified in an API’s OpenAPI specification.

Clients are recommended to use these headers and log them for both privacy logging and operational purposes (e.g. when troubleshooting a problem with CBSS service desk).

CBSS uses UUIDs as trace IDs. For responses of type Problem JSON, the instance field will have the same value as the BelGov-Trace-Id HTTP response header prefixed with urn:uuid:.

6. Response

6.1. Problems

6.1.1. Problem Type Definitions

CBSS APIs use both standardized Belgif problem types and CBSS defined problem types.

It should be noted that these problems are formatted according to the Problem Detail as specified by RFC 9457 (to which the Belgif has added some further restrictions and extensions) listing as major semantic properties :

  • status: the HTTP status code

  • type: A unique identifier for the type of the problem. These URNs will be either Belgif problem types, or the CBSS types as listed below.

  • title: a short summary of the problem type in English

  • instance: A unique identifier of the problem instance which for CBSS has structure urn:cbss:trace-id:<uuid> with the <uuid> corresponding to the value of the BelGov-Trace-Id HTTP response header.

  • detail: consumer-friendly information about the specific failing request

When parsing these problems for information, you SHOULD only use the property type or issues/type (see subtypes). The other properties title and detail, which contain human-readable explanations, however SHOULD NOT be parsed for information, as also noted in the RFC 9457
Belgif problem types

For the standardized Belgif problem types we refer to the Belgif REST guide.

CBSS problem types

Common CBSS problem types that can be used across all CBSS REST APIs are listed below. These are defined as URNs of format urn:problem-type:cbss:<type>. CBSS APIs may also define their own problem types for specific business errors. Those API-local problem types are defined as URNs of format urn:problem-type:cbss:<apiName>:<type>.

Insufficiently Integrated SSIN

Status code 403 Forbidden

Description The client doesn’t have the right to invoke an operation on the given resource for a given SSIN due to the SSIN being insufficiently integrated according to the constraints defined for the combination of client/legalContext/resource/operation. The defined constraints can be found in the cookbook annex for the client.

GET /cards?ssin=11111111111
Legal-Context: CLIENT:SOME_LEGAL_CONTEXT
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

 {
   "type": "urn:problem-type:cbss:insufficientlyIntegratedSsin",
   "title": "Insufficiently Integrated SSIN",
   "status": 403,
   "detail": "The SSIN is not sufficiently integrated for your organization",
   "ssin": "11111111111",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }

Status code 403 Forbidden

Description The client doesn’t have the right to invoke an operation on the given resource for a given legal context. The defined legal context(s) can be found in the cookbook annex for the client.

GET /cards?ssin=11111111111
Legal-Context: CLIENT:SOME_LEGAL_CONTEXT
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

 {
   "type": "urn:problem-type:cbss:unauthorizedLegalContext",
   "title": "Unauthorized Legal Context",
   "status": 403,
   "detail": "Access is not allowed with the given legal context",
   "legalContext": "CLIENT:SOME_LEGAL_CONTEXT",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }

6.1.2. Issue Type Definitions

Issue types can be used in the type property under issues in a badRequest problem. CBSS APIs use both standardized Belgif issue types and CBSS defined issue types.

Belgif issue types

For the standardized Belgif issue types we refer to the Belgif REST guide.

CBSS issue types

Common CBSS issue types that can be used across all CBSS REST APIs are listed below. These are defined as URNs of format urn:problem-type:cbss:input-validation:<type>. CBSS APIs may also define their own issue types for specific input validation errors. Those API-local issue types are defined as URNs of format urn:problem-type:cbss:input-validation:<apiName>:<type>.

CBSS REST APIs may perform additional cross-input validations that cannot be enforced through the OpenAPI definition. Because such issues relate to more than 1 input parameter, and the Belgif InputValidationIssue type only allows a singular in/name/value reference, CBSS APIs return a custom InputValidationIssue extension in this case with an inputs array of in/name/value references.

CBSS single-input validation issue types
type title additional properties

urn:problem-type:cbss:input-validation:invalidStructure

Input value has invalid structure

urn:problem-type:cbss:input-validation:outOfRange

Input value is out of range

minimum, maximum

urn:problem-type:cbss:input-validation:referencedResourceNotFound

Referenced resource not found (deprecated)

urn:problem-type:cbss:input-validation:rejectedInput

Input is not allowed in this context

urn:problem-type:cbss:input-validation:requiredInput

Input is required in this context

urn:problem-type:cbss:input-validation:replacedSsin

SSIN has been replaced, use new SSIN

replacedBy: "<new SSIN>", replacedByHref: "<new href>"

urn:problem-type:cbss:input-validation:canceledSsin

SSIN has been canceled

urn:problem-type:cbss:input-validation:invalidPeriod

Period is invalid
Belgif standardization effort of these issue types is ongoing.
CBSS cross-input validation issue types
type title

urn:problem-type:cbss:input-validation:exactlyOneOfExpected

Exactly one of these inputs must be present

urn:problem-type:cbss:input-validation:anyOfExpected

Any of these inputs must be present

urn:problem-type:cbss:input-validation:zeroOrExactlyOneOfExpected

Exactly one or none of these inputs must be present

urn:problem-type:cbss:input-validation:zeroOrAllOfExpected

All or none of these inputs must be present

urn:problem-type:cbss:input-validation:equalExpected

These inputs must be equal
Belgif standardization effort of these issue types is ongoing.

Examples of common CBSS issue types (including one for an API-local issue type) in a badRequest problem :

GET /cards?ssin=11111111111
Legal-Context: CLIENT:SOME_LEGAL_CONTEXT
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "urn:problem-type:belgif:badRequest",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
  "status": 400,
  "title": "Bad Request",
  "detail": "The input message is incorrect",
  "issues": [
    {
      "type": "urn:problem-type:cbss:input-validation:replacedSsin",
      "title": "SSIN has been replaced, use new SSIN",
      "detail": "SSIN 11111111111 has been replaced by 22222222222",
      "in": "query",
      "name": "ssin",
      "value": "11111111111",
      "replacedBy": "22222222222",
      "replacedByHref": "/cards?ssin=22222222222"
    },
    {
      "type": "urn:problem-type:cbss:input-validation:someCbssApi:someIssue",
      "title": "Some issue with the request",
      "detail": "The issue concerns this and that",
      "in": "query",
      "name": "ssin",
      "value": "11111111111"
    }
 ]
}
Example of a cross-input validation issue type
{
  "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",
  "issues": [
    {
      "type": "urn:problem-type:cbss:input-validation:exactlyOneOfExpected",
      "title": "Exactly one of these inputs must be present",
      "detail": "Exactly one of these inputs must be present: sector, enterpriseNumber",
      "inputs": [ (1)
          {
            "in": "query",
            "name": "sector",
            "value": null
          },
          {
            "in": "query",
            "name": "enterpriseNumber",
            "value": null
          }
        ]
    }
  ]
}
1 Custom CBSS extension of Belgif InputValidationIssue with inputs array

6.1.3. API Problem Specification

CBSS REST APIs define the specific problems returned in each operation but some generic problems are not defined in each OpenAPI. The general guideline is that business problems are always explicitly defined in the OpenAPI of the application in contrast with more technical issues which are considered more generic and are deemed implicitly present.

Implicit problems

The problems below may be returned by every operation in a CBSS API, even if they aren’t specified in the API’s OpenAPI specification.

HTTP Status Problem Type Description

400 Bad Request

urn:problem-type:belgif:badRequest

When request isn’t conform to the OpenAPI document

When this Problem type is used for other cases than schema violation issues (e.g. business validation issues, issues with the SSIN, …​), the problem response will be explicitly specified in the API’s OpenAPI specification.

401 Unauthorized

urn:problem-type:belgif:noAccessToken

Missing access token in request

urn:problem-type:belgif:invalidAccessToken

Invalid access token in request

urn:problem-type:belgif:expiredAccessToken

Expired access token in request

403 Forbidden

urn:problem-type:belgif:missingScope

Access token doesn’t have the required scope to access the operation

urn:problem-type:belgif:missingPermission

The client is not authorized to invoke an operation on the given resource. The refusal is not related to the consumer scope but to access to the specific resource itself (data access).

urn:problem-type:cbss:unauthorizedLegalContext

Access to this operation is not allowed with the given legal context

404 Not Found

urn:problem-type:belgif:resourceNotFound

Can be returned when path not defined in OpenAPI specification is called. In other use cases, problem type is defined in the API’s OpenAPI specification.

413 Payload Too Large

urn:problem-type:belgif:payloadTooLarge

The client request was refused because its payload is too large.

429 Too many requests

urn:problem-type:belgif:tooManyRequests

No more new requests are accepted because the client quota was exceeded.

urn:problem-type:belgif:tooManyFailedRequests

No more new requests are accepted because the client quota for failed requests was exceeded.

500 Internal Server Error

urn:problem-type:belgif:internalServerError

Unexpected problem.

502 Bad Gateway

urn:problem-type:belgif:badGateway

Error in communication of CBSS with external provider.

503 Service Unavailable

urn:problem-type:belgif:serviceUnavailable

The service is unavailable, because of a planned or unplanned downtime.

6.2. Warnings

Some operations of CBSS APIs may optionally return a warnings array for reporting non-blocking issues that occurred during processing of the request.

These warnings consist of "type", "href", "title" and "detail" properties (similar to problems and issues). Additionally, they can have array properties that reference the "inputs" and/or "outputs" that relate to the warning.

Belgif standardization effort of warnings is ongoing.

6.2.1. CBSS warning types

Common CBSS warning types that can be used across all CBSS REST APIs are listed below. These are defined as URNs of format urn:warning-type:cbss:<type>. CBSS APIs may also define their own warning types, defined as URNs of format urn:warning-type:cbss:<apiName>:<type>.

type title

urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider

Insufficiently Integrated SSIN for provider

urn:warning-type:cbss:replacedSsin

The SSIN has been replaced

urn:warning-type:cbss:readOnlyPropertyIgnored

The provided readOnly property has been ignored

urn:warning-type:cbss:paginationExceeded

The requested page exceeds the number of pages in the collection
Example of a response with a warning
{
  "items": [],
  "total": 0,
  "warnings": [
    {
      "type": "urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider",
      "title": "Insufficiently Integrated SSIN for provider",
      "detail": "The SSIN 11111111111 is not sufficiently integrated for the provider",
      "inputs": [
        {
          "in": "query", // or "body" or "path"
          "name": "ssin",
          "value": 11111111111
        }
      ]
    }
  ]
}
Example of a response with a warning with additional details
{
  "status": "ok",
  "warnings": [
    {
      "type": "urn:warning-type:cbss:replacedSsin",
      "title": "The SSIN has been replaced",
      "detail": "SSIN 11111111111 has been replaced by 22222222222",
      "inputs": [
        {
          "in": "path",
          "name": "ssin",
          "value": 11111111111
        }
      ],
      "replacedBy": "22222222222"
    }
  ]
}

6.3. No data found

When a CBSS REST API is used to obtain data from another provider, there are several ways in which the absence of data may be represented.

These differences ultimately depend on the cardinality of the target resource.

Consider the following operation:

GET /items/{id}/otherItems

If the document resource /items/{id} is missing, a Resource Not Found Problem is returned. If however it exists but the subresource collection otherItems is empty, an empty collection is returned.

Now consider the following operation:

GET /items?id=123456

The resource being consulted is a collection. If the item with the given id is absent, an empty collection is returned.

If the {id} is an SSIN, CBSS typically also verifies the integration for the provider. If this SSIN is not sufficiently integrated for the provider, this is also considered as a "no data found". Additional information is provided to help the client distinguish between a CBSS "no data found" response and a provider’s "no data found" response.

The insufficient integration for the provider can be returned as a Resource Not Found Problem with a specific issue urn:problem-type:cbss:input-validation:insufficientlyIntegratedSsinForProvider or as an empty collection with a specific warning urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider. Again, this is dependent on the cardinality of the missing resource.

The following table gives an overview of the different possibilities and links to the examples below.

Case

Operation

SSIN sufficiently integrated for the provider

Situation at the provider

Result

SSIN in query/body

GET /items?ssin=11111111111 &startDate=2024-01-01 &endDate=2024-12-31

POST /items/searchBySsinAndPeriod {"ssin"="11111111111", "startDate"=2024-01-01, "endDate"="2024-12-31"}

GET /items?ssin=11111111111

POST /items/searchBySsin {"ssin"="11111111111"}

Yes

Collection items empty after filter ssin=11111111111

Empty collection

No

N/A

Empty collection with warning SSIN not sufficiently integrated for the provider

SSIN in path

GET /items/{ssin}

Yes

Document item for {ssin} not found

Resource Not Found for resource identified by SSIN in path

No

N/A

Resource Not Found with issue SSIN not sufficiently integrated for the provider

GET /items/{ssin}/childDocument

Yes

Document item for {ssin} found, but document childDocument not found

Resource Not Found for child resource

Yes

Document item for {ssin} not found

Resource Not Found for resource identified by SSIN in path

No

N/A

Resource Not Found with issue SSIN not sufficiently integrated for the provider

GET /items/{ssin}/childItems

GET /items/{ssin}/childItems? criterium=Y

POST /items/{ssin}/searchChildItems {"criterium"="Y"}

Yes

Document item for {ssin} found, but collection childItems empty

Empty collection

Yes

Document item for {ssin} not found

Resource Not Found for resource identified by SSIN in path

No

N/A

Resource Not Found with issue SSIN not sufficiently integrated for the provider

GET /items/{ssin}/childItems? startDate=2024-01-01 &endDate=2024-12-31

POST /items/{ssin}/searchChildItems {"startDate"="2024-01-01", "endDate"="2024-12-31"}

Yes

Document item for {ssin} found, but collection childItems empty

Empty collection

Yes

Document item for {ssin} not found

Resource Not Found for resource identified by SSIN in path

No. SSIN may be integrated for another period and have a document item .

N/A

Empty collection with warning SSIN not sufficiently integrated for the provider
Empty collection 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [],
  "total": 0
}
Empty collection with warning SSIN not sufficiently integrated for the provider 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [],
  "total": 0,
  "warnings": [
    {
      "type": "urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider",
      "title": "Insufficiently Integrated SSIN for provider",
      "detail": "The SSIN 11111111111 is not sufficiently integrated for the provider",
      "inputs": [
        {
          "in": "query", // or "body" or "path"
          "name": "ssin",
          "value": 11111111111
        }
      ]
    }
  ]
}
Resource Not Found for resource identified by SSIN in path 
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "urn:problem-type:belgif:resourceNotFound",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No data found for the given SSIN 11111111111",
  "issues": {
    "in": "path",
    "name": "ssin",
    "value": 11111111111
  },
  "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
}
Resource Not Found for child resource 
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "urn:problem-type:belgif:resourceNotFound",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No resource /items/11111111111/childDocument found",
  "issues": {
    "in": "path",
    "name": "childDocument",
    "detail": "item with SSIN 11111111111 does not have a childDocument"
  },
  "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
}
Resource Not Found with issue SSIN not sufficiently integrated for the provider 
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "urn:problem-type:belgif:resourceNotFound",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No data found for the given SSIN 11111111111",
  "issues": [
    {
      "type": "urn:problem-type:cbss:input-validation:insufficientlyIntegratedSsinForProvider",
      "title": "Insufficiently Integrated SSIN for provider",
      "detail": "The SSIN 11111111111 is not sufficiently integrated for the provider",
      "in": "path",
      "name": "ssin",
      "value": 11111111111
    }
  ],
  "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
}

6.4. Unauthorized Properties

Despite having access to the requested resource with the given scope and legal context, a client might not be authorized to receive all response body properties that have been defined in the OpenAPI specification. In that case, those unauthorized properties are removed from the response. The API returns a Cbss-Unauthorized-Properties HTTP header to inform the client of the authorization filter that was applied to the response. The cookbook annex for the client documents the unauthorized properties per legal context. This is the REST equivalent of 4.2 dataFilters for CBSS SOAP services.

The Cbss-Unauthorized-Properties HTTP header value consists of a comma-separated list of JSONPath expressions.

Note that this list is static for the given client / legal context / resource: the existence of an unauthorized property in this list does not imply that the property was present in the original response body.

Original response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@gmail.com",
  "password": "topsecret"
}
Client response with Cbss-Unauthorized-Properties
HTTP/1.1 200 OK
Content-Type: application/json
Cbss-Unauthorized-Properties: $.password, $.phoneNumber

{
  "name": "John Doe",
  "email": "john.doe@gmail.com"
}

7. Monitoring

All CBSS REST APIs provide a GET /health endpoint that is compliant with the Belgif specification.

This monitoring endpoint is secured with a generic scope that is implicitly granted to all known clients: scope:cbss:api:monitoring.

Calls to this endpoint do not require a Legal-Context HTTP header.

Example /health response payload
HTTP/1.1 200 OK (1)
Content-Type: application/json

{
  "status": "UP", (2)
  "apiVersion": "1.0-5" (3)
}
1 the HTTP status code (200 for UP/DEGRADED, 503 for DOWN)
2 the API status:

  • UP: the API functions as expected

  • DEGRADED: the API is partly unavailable (reduced functionality, slow, …​)

  • DOWN: the API is suffering unexpected failures
3 the API version (for information purposes)

Note that the /health responses are cached for 30 seconds, so the data is not real-time.

Clients should refrain from sending "real" API requests for monitoring purposes, and instead use this provided /health endpoint.

8. Availability and performance

See our website (nl / fr).

9. Contact

In case of problems, please contact the CBSS Service Desk (nl / fr).

Please add enough information for us to identify the message from the issue:

  • Environment (test/acceptance/production)

  • The ticket, i.e. the BelGov-Trace-Id from the request or the response

  • Alternatively,

    • the request path

    • the headers + body of the request and the response

    • date and time

10. Annex

10.1. Mapping table SOAP vs. REST

For clients migrating from a CBSS SOAP oriented model we provide a simple mapping table between standard CBSS SOAP responses and their CBSS REST alternative.

Case

SOAP

REST

Value

Code

Code

Type
Issue

Data Found

DATA_FOUND

MSG00000

200

/

No Data Found

NO_DATA_FOUND

MSG00100

200 (empty collection)

/

404 (missing (child) resource)

urn:problem-type:belgif:resourceNotFound

Error in communication with the destination/supplier

Soapenv:Server

MSG00002

502

urn:problem-type:belgif:badGateway

Internal Error

Soapenv:Server

MSG00003

500

urn:problem-type:belgif:internalServerError

The request has an invalid structure

Soapenv:Client

MSG00004

400

urn:problem-type:belgif:badRequest
urn:problem-type:belgif:input-validation:schemaViolation

SSIN Unknown

NO_RESULT

MSG00005

400

urn:problem-type:belgif:badRequest
urn:problem-type:belgif:input-validation:referencedResourceNotFound

SSIN Replaced

NO_RESULT

MSG00006

400

urn:problem-type:belgif:badRequest
urn:problem-type:cbss:input-validation:replacedSsin

SSIN Canceled

NO_RESULT

MSG00007

400

urn:problem-type:belgif:badRequest
urn:problem-type:cbss:input-validation:canceledSsin

Invalid Data

NO_RESULT

MSG00008

400

urn:problem-type:belgif:badRequest
urn:problem-type:cbss:input-validation:*

SSIN Invalid Structure

NO_RESULT

MSG00011

400

urn:problem-type:belgif:badRequest
urn:problem-type:cbss:input-validation:invalidStructure

Insufficiently Integrated SSIN Client

NO_RESULT

MSG00012

403

urn:problem-type:cbss:insufficientlyIntegratedSsin

Unauthorized Legal Context

NO_RESULT

MSG00013

403

urn:problem-type:cbss:unauthorizedLegalContext

The SSIN is not sufficiently integrated for the provider of the data

NO_DATA_FOUND

MSG00021

200 (empty collection)

urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider

404 (missing SSIN resource)

urn:problem-type:belgif:resourceNotFound+ urn:problem-type:cbss:input-validation:ssinInsufficientlyIntegratedForProvider

10.1.1. Examples SOAP vs REST

No Data Found
REST (empty collection)
 {
   "items": [],
   "total": 0
 }
REST (missing resource)
 {
   "type": "urn:problem-type:belgif:resourceNotFound",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
   "title": "Resource Not Found",
   "status": 404,
   "detail": "No data found for the given SSIN 11111111111",
   "issues": {
     "in": "path",
     "name": "ssin",
     "value": 11111111111
   },
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
REST (missing child resource)
 {
   "type": "urn:problem-type:belgif:resourceNotFound",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
   "title": "Resource Not Found",
   "status": 404,
   "detail": "No resource /items/11111111111/childDocument found",
   "issues": {
     "in": "path",
     "name": "childDocument",
     "detail": "item with SSIN 11111111111 does not have a childDocument"
   },
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_DATA_FOUND</value>
  <code>MSG00100</code>
  <description>Treatment successful, but no data found at the supplier</description>
</status>
Error in communication with the destination/supplier
REST
 {
   "type": "urn:problem-type:belgif:badGateway",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/badGateway.html",
   "status": 502,
   "title": "Bad Gateway",
   "detail": "Error in communication with upstream service",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Server</faultcode>
      <faultstring>Error in communication with the destination/supplier</faultstring>
      <faultactor>http://www.ksz-bcss.fgov.be</faultactor>
      <detail>
        <ns:faultInfo xmlns:ns="http://kszbcss.fgov.be/intf/faultinfo">
          <informationCustomer>
            <ticket>…</ticket>
            <timestampSent>…</timestampSent>
            <customerIdentification>
              <cbeNumber>…</cbeNumber>
            </customerIdentification>
          </informationCustomer>
          <informationCBSS>
            <ticketCBSS>…</ticketCBSS>
            <timestampReceive>…</timestampReceive>
            <timestampReply>…</timestampReply>
          </informationCBSS>
          <detail>
            <severity>FATAL</severity>
            <reasonCode>MSG00002</reasonCode>
            <diagnostic>Error in communication with the destination/supplier</diagnostic>
            <authorCode>http://www.ksz-bcss.fgov.be/</authorCode>
          </detail>
        </ns:faultInfo>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>
Internal Error
REST
 {
   "type": "urn:problem-type:belgif:internalServerError",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/internalServerError.html",
   "status": 500,
   "title": "Internal Server Error",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Server</faultcode>
      <faultstring>Internal error</faultstring>
      <faultactor>http://www.ksz-bcss.fgov.be</faultactor>
      <detail>
        <ns:faultInfo xmlns:ns="http://kszbcss.fgov.be/intf/faultinfo">
          <informationCustomer>
            <ticket>…</ticket>
            <timestampSent>…</timestampSent>
            <customerIdentification>
              <cbeNumber>…</cbeNumber>
            </customerIdentification>
          </informationCustomer>
          <informationCBSS>
            <ticketCBSS>…</ticketCBSS>
            <timestampReceive>…</timestampReceive>
            <timestampReply>…</timestampReply>
          </informationCBSS>
          <detail>
            <severity>FATAL</severity>
            <reasonCode>MSG00003</reasonCode>
            <diagnostic>Internal error</diagnostic>
            <authorCode>http://www.ksz-bcss.fgov.be/</authorCode>
          </detail>
        </ns:faultInfo>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>
The request has an invalid structure
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:schemaViolation",
       "title": "Input value is invalid with respect to the schema",
       "detail": "ECMA 262 regex does not match input string",
       "in": "header",
       "name": "Legal-Context",
       "value": "test"
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Client</faultcode>
      <faultstring>The request has an invalid structure</faultstring>
      <faultactor>http://www.ksz-bcss.fgov.be</faultactor>
      <detail>
        <ns:faultInfo xmlns:ns="http://kszbcss.fgov.be/intf/faultinfo">
          <informationCustomer>
            <ticket>…</ticket>
            <timestampSent>…</timestampSent>
            <customerIdentification>
              <cbeNumber>…</cbeNumber>
            </customerIdentification>
          </informationCustomer>
          <informationCBSS>
            <ticketCBSS>…</ticketCBSS>
            <timestampReceive>…</timestampReceive>
            <timestampReply>…</timestampReply>
          </informationCBSS>
          <detail>
            <severity>FATAL</severity>
            <reasonCode>MSG00004</reasonCode>
            <diagnostic>The request has an invalid structure</diagnostic>
            <authorCode>http://www.ksz-bcss.fgov.be/</authorCode>
          </detail>
        </ns:faultInfo>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>
SSIN Unknown
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:belgif:input-validation:referencedResourceNotFound",
       "title": "Referenced resource not found",
       "detail": "SSIN 11111111111 does not exist",
       "in": "path",
       "name": "ssin",
       "value": "11111111111"
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00005</code>
  <description>The SSIN given in request does not exist</description>
</status>
SSIN Replaced
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:replacedSsin",
       "title": "SSIN has been replaced, use new SSIN",
       "detail": "SSIN 11111111111 has been replaced by 22222222222",
       "in": "path",
       "name": "ssin",
       "value": "11111111111",
       "replacedBy": "22222222222",
       "replacedByHref": "https://api.ksz-bcss.fgov.be/service/v1/examples/22222222222"
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00006</code>
  <description>The SSIN given in request has been replaced</description>
</status>
SSIN Canceled
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:canceledSsin",
       "title": "SSIN has been canceled",
       "detail": "SSIN 11111111111 has been canceled",
       "in": "path",
       "name": "ssin",
       "value": "11111111111"
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00007</code>
  <description>The SSIN given in request is canceled</description>
</status>
Invalid Data
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:invalidPeriod",
       "title": "Period is invalid",
       "detail": "endDate should not preceed startDate",
       "inputs": [
         {
           "in": "query",
           "name": "startDate",
           "value": "2023-01-01"
         },
         {
           "in": "query",
           "name": "endDate",
           "value": "2022-01-01"
         }
       ]
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00008</code>
  <description>The request contains invalid data. Please check your message content.</description>
  <information>
    <fieldName>Invalid Period : enddate before begindate</fieldName>
    <fieldValue>2022-01-01 lies before 2023-01-01</fieldValue>
  </information>
</status>
SSIN Invalid Structure
REST
 {
   "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",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:invalidStructure",
       "title": "Input value has invalid structure",
       "detail": "SSIN 11111111111 is invalid",
       "in": "path",
       "name": "ssin",
       "value": "11111111111"
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00011</code>
  <description>The structure of the SSIN given in request is invalid</description>
</status>
Insufficiently Integrated SSIN Client
REST
 {
   "type": "urn:problem-type:cbss:insufficientlyIntegratedSsin",
   "title": "Insufficiently Integrated SSIN",
   "status": 403,
   "detail": "The SSIN is not sufficiently integrated for your organization",
   "ssin": "11111111111",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00012</code>
  <description>The SSIN is not sufficiently integrated for your organization</description>
</status>
Unauthorized Legal Context
REST
 {
   "type": "urn:problem-type:cbss:unauthorizedLegalContext",
   "title": "Unauthorized Legal Context",
   "status": 403,
   "detail": "Access is not allowed with the given legal context",
   "legalContext": "CLIENT:SOME_LEGAL_CONTEXT",
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_RESULT</value>
  <code>MSG00013</code>
  <description>Access to this operation is not allowed with the given legal context</description>
</status>
The SSIN is not sufficiently integrated for the provider of the data
REST (empty collection)
 {
   "items": [],
   "total": 0,
   "warnings": [
     {
       "type": "urn:warning-type:cbss:insufficientlyIntegratedSsinForProvider",
       "title": "Insufficiently Integrated SSIN for provider",
       "detail": "The SSIN 11111111111 is not sufficiently integrated for the provider",
       "inputs": [
         {
           "in": "query", // or "body" or "path"
           "name": "ssin",
           "value": 11111111111
         }
       ]
     }
   ]
 }
REST (missing SSIN resource)
 {
   "type": "urn:problem-type:belgif:resourceNotFound",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html",
   "title": "Resource Not Found",
   "status": 404,
   "detail": "No data found for the given SSIN 11111111111",
   "issues": [
     {
       "type": "urn:problem-type:cbss:input-validation:insufficientlyIntegratedSsinForProvider",
       "title": "Insufficiently Integrated SSIN for provider",
       "detail": "The SSIN 11111111111 is not sufficiently integrated for the provider",
       "in": "path",
       "name": "ssin",
       "value": 11111111111
     }
   ],
   "instance": "urn:cbss:trace-id:00000000-0000-0000-0000-000000000000"
 }
SOAP
<status>
  <value>NO_DATA_FOUND</value>
  <code>MSG00021</code>
  <description>The SSIN is not sufficiently integrated for the provider of the data</description>
</status>