Data service

Deze pagina’s zijn in het engels ten behoeve van mogelijk internationale ontwikkelaars


This endpoint MUST be implemented by the following roles:

Data SERVICE PROVIDER


Data service providers are free to implement a data service within the DSGO to provide a service to achieve business value according their own design. Data services provided within the DSGO conform to the DSGO specifications. This page gives an abstract overview of elements which may be used in data services.

DSGO.Basis: Data service providers MUST expose their resources in conformance with the trust framework

Request

Requests can make use of any HTTP method and can contain any extra headers. Parameters are undefined because they vary for each data service provider due to their business specific logic.

Note, additional headers for security, statefulness, application functionality could be added and is out of scope of this specification.

Request headers

For information about the parameters that are common to the trust framework’s API’s see Generic API Requirements.

Parameter

Type

Description

Parameter

Type

Description

Authorization

Optional

String

MUST contain an OAuth 2.0 authorization based on bearer token. MUST contain “Bearer " + access token value. This parameter is optional and may be used by data service providers who wish to use an access token as authorization information for their data service.

Data service consumers can request access tokens via the /token endpoint. See Access Token for more information.

broker_evidence

Optional

String

MUST contain a broker_token object containing DSGO broker evidence regarding the data service broker. This parameter is optional and may be used by data service brokers who request a data service on behalf of data service consumers they service.

Data service brokers can obtain broker evidence via the /brokers endpoint. See Datadienstbrokers for more information.

Note, broker_evidence MUST be used in combination with the client_assertion parameter. If broker_evidence is used, the accessSubject in the brokerEvidence object MUST be validated to match the client_id in the client_assertion. If this matches, the policyIssuer in the brokerEvidence MUST be considered the data service consumer.

Note, broker_evidence MAY NOT be used in combination with delegation_evidence.

client_assertion

Optional

String

MUST contain a signed DSGO JSON Web Token. This parameter may contain a DSGO Authenticatie JWT used for of the data service consumer. Alternatively this parameter may contain a DSGO Onweerlegbaarheid JWT used by data service consumers or required by data service providers who wish to ensure for non-repudiation of the data service request. If this parameter contains a Onweerlegbaarheid JWT, the Digest header must also be included.

See Authenticatie and Onweerlegbaarheid for more information.

delegation_evidence

Optional

String

MUST contain a delegation_token object containing delegation evidence regarding the requested service. This parameter is optional and may be used by data service providers who wish to enable data entitled parties to delegate their rights in regard to the data service to (potential) data service consumers.

Data service consumers can obtain delegation evidence via the /delegation endpoint. See Delegation for more information.

Note, delegation_evidence MUST be used in combination with the client_assertion parameter. If delegation_evidence is used, the accessSubject in the delegationEvidence object MUST be validated to match the client_id in the client_assertion. If this matches, the policyIssuer in the delegationEvidence MUST be considered the data service consumer.

Note, delegation_evidence MAY NOT be used in combination with broker_evidence.

Digest

Optional

String

MUST contain a SHA256 hash (according to RFC 9530) of the HTTP body with the matching algorithm identifier SHA-256as defined in ETSI TS 119 182-1. This parameter is optional and may be used by data service consumers or required by data service providers who wish to ensure for non-repudiation of the data service request.

See Onweerlegbaarheid for more information.

LicensePurpose

Optional

String

MUST contain a reference to the legal document under which the data service is made available. MUST be equal to one or more of the licence codes, prepended with a “DSGO." prefix. This parameter describes the purpose of the licence the data service consumer request for the data in the data service response.

See Licenties for more information.

Request body

Given the scope of the DSGO, the trust framework is data agnostic, and any type of content could be offered in data services. See Wat is een datadienst? for more information. It is the responsibility of the data service provider to determine the data resource offered in a data service in the data service specification. Depending on the data service this service content could be included in the HTTP body of the request or response. Although the data service provider is free to choose whatever data standard they see fit for their service, the DSGO presents the following agreement as a best practice.

Responses

Data service response can make use of any HTTP status code and can contain any extra headers. Parameters are undefined because they vary for each data service provider due to their business specific logic.

Response headers

Parameter

Type

Description

Parameter

Type

Description

broker_evidence

Optional

String

Note, broker_evidence MUST be used in combination with the client_assertion parameter. If broker_evidence is used, the accessSubject in the brokerEvidence object MUST be validated to match the client_id in the client_assertion. If this matches, the policyIssuer in the brokerEvidence MUST be considered the data service provider.

client_assertion

Optional

String

MUST contain a signed DSGO Onweerlegbaarheid JWT. This parameter is optional and may be used by data service providers or required by data service consumers who wish to ensure for non-repudiation of the data service response. If this parameter is used, the Digest header must also be included.

See Onweerlegbaarheid for more information.

Digest

Optional

String

MUST contain a SHA256 hash (according to RFC 9530) of the HTTP body with the matching algorithm identifier SHA-256as defined in ETSI TS 119 182-1. This parameter is optional and may be used by data service providers or required by data service consumers who wish to ensure for non-repudiation of the data service response.

See Onweerlegbaarheid for more information.

LicensePurpose

Optional

String

MUST contain a reference to the legal document under which the data service is made available. MUST be equal to one or more of the licence codes, prepended with a “DSGO." prefix. This parameter describes the purpose of the licence the data service consumer receives in the data service response.

See Licenties for more information.

LicenseSubLicense

Optional

String

Optional DSGO specific value describing the amount of sub license(s) the Data Service Provider is allowed to issue for the data in the data service response.

LicenseEndDate

Optional

String

MUST contain the date and time which describes the duration of the license for the data in the data service response. MUST be a UNIX timestamp, following the timestamp conventions.

Response body

See Request body.