Guide 7. Implement data service

Data service providers are free to implement a data service to achieve business value according their own design, but they must conform to DSGO specifications.

A data service provider should define an endpoint for a resource in order to enable a specific data service in the DSGO. As the exact implementation of data service is highly dependent on the specific resource, the context, and the needs of the data service provider, no specific service is presented here.

Therefore, this page contains examples for all methods of a generic resource endpoint as defined by the DSGO (called /resources), which a Data Service Provider can use to structure its own endpoints accordingly.

The data service could require additional information being shared through the HTTP Request or Response headers. The Authorization header including the Bearer access_token is mandatory. Other headers are optional and could include:

• Digest and client_assertion for Non-repudiation;

• delegation_evidence to share delegations as a data service consumer to the data service provider;

• LicensePurpose, LicenseSubLicense, and LicenseEndDate to share license conditions regarding the data service and/or the data.

• Additional service specific headers for security, statefulnes, application functionality etc.. could be added but this is out of scope of this specification.

Please see the DSGO framework section on data service for more information.

All examples can be tested on SwaggerHub.

Example getting a list of data services in the collection

get

This is an example of a HTTP GET to get a list of the available resources within the collection

Authorizations

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Responses

200

OK

application/json

get

HTTPcURLJavaScriptPython

GET /DSGO/developer-portal/1.1.1/resources HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Accept: */*

200

OK

{
  "count": 4,
  "resources": [
    {
      "id": "001",
      "href": "/resources/001",
      "description": "Hex value of the colour red"
    },
    {
      "id": "002",
      "href": "/resources/002",
      "description": "Hex value of the colour green"
    },
    "..."
  ]
}

Example creating data

post

This is an example of a HTTP POST to create data at a resource

Authorizations

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Body

objectOptional

resource should be according to the data format specified in the specific data service

Responses

201

Created

application/json

post

HTTPcURLJavaScriptPython

POST /DSGO/developer-portal/1.1.1/resources HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 92

{
  "data": {
    "colour": "magenta",
    "value": "#f0f",
    "description": "Hex value of the colour magenta"
  }
}

201

Created

{
  "id": "005",
  "href": "/resources/005",
  "description": "Hex value of the colour magenta"
}

Example of getting the data in a specific resource

get

This is an example of a HTTP GET to request a specific resource

Authorizations

Path parameters

idstringRequired

resource URI

Example: 005

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Responses

200

OK

application/json

Responseobject

resource should be according to the data format specified in the specific data service

404

Not Found

get

HTTPcURLJavaScriptPython

GET /DSGO/developer-portal/1.1.1/resources/{id} HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Accept: */*

{
  "data": {
    "colour": "magenta",
    "value": "#f0f",
    "description": "Hex value of the colour magenta"
  }
}

Example replacing data at a specific resource

put

This is an example of a HTTP PUT to replace data at a resource

Authorizations

Path parameters

idstringRequired

resource URI

Example: 005

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Body

objectOptional

resource should be according to the data format specified in the specific data service

Responses

200

OK

204

No content

404

Not found

put

HTTPcURLJavaScriptPython

PUT /DSGO/developer-portal/1.1.1/resources/{id} HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "data": {
    "colour": "dark red",
    "value": "#c00",
    "description": "Hex value of the colour red"
  }
}

No content

Example deleting data

delete

This is an example of a HTTP DELETE to remove data at a resource

Authorizations

Path parameters

idstringRequired

Resource URI

Example: 005

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Responses

200

OK

404

Not found

delete

HTTPcURLJavaScriptPython

DELETE /DSGO/developer-portal/1.1.1/resources/{id} HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Accept: */*

No content

Example editing data at a specific resource

patch

This is an example of a HTTP PATCH to edit data at a resource

Authorizations

Path parameters

idstringRequired

Resource URI

Example: 005

Header parameters

delegation_evidencestringOptional

regarding the requested service. The Service Consumer can obtain this evidence from an Authorization Registry / Entitled Party before requesting a specific service.

client_assertionstringOptional

Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a 'service broker' pattern. It is used to prove that the 'brokering' Service Consumer indeed has had a request from the original Service Consumer

digeststringOptional

digest

LicensePurposestringOptional

License purpose

LicenseSubLicensestringOptional

License purpose

LicenseEndDatestringOptional

License purpose

service_header_genericstringOptional

optional service specific headers

Body

operationstringOptional

Operation to be performed on the resource

Example: add, remove, replace, ...

pathstringOptional

JSON pointer to the resource the operation should work on

Example: description

valuestringOptional

Data to be edited at the resource

Example: Hex value of the colour

Responses

200

OK

204

No content

404

Not found

patch

HTTPcURLJavaScriptPython

PATCH /DSGO/developer-portal/1.1.1/resources/{id} HTTP/1.1
Host: virtserver.swaggerhub.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 89

[
  {
    "operation": "replace",
    "path": "description",
    "value": "Hex value of the colour dark red"
  }
]

No content