CIM XML og CIM JSON webservice interface

1. Indledning

Dette dokument beskriver hvordan elektronisk kommunikation med Datahub 3 skal varetages.

Eksemplerne her indeholder ikke de korrekte informationer for de forskellige miljøer.

De kan findes her. Datahub 3 preprod - Edi Kommunikation

Begge dokumentformater afleveres via den samme kanal til DataHub 3. Kaldet til DataHub fortæller hvilken type data der bliver sendt og vil blive valideret på baggrund af dette.

2.       Kommunikation

Kommunikationskanalen til CIM er baseret på http protokollen. Der gøres brug af standard http verber, http-headers og status koder når der sendes et datasæt til DataHub. 

2.1       HTTP kommunikation

De forskellige http-verber benyttes til at udtrykke hvad man ønsker at udfører i DataHub. 

2.1.1      HTTP POST

Hvis man vil aflevere et datasæt til DataHub dannes forespørgslen som en POST. Selve doku- mentet skrives i body på HTTP forespørgslen. Ved hjælp af http header værdier beskrives ind- holdet. For at sende i CIM XML sættes Content-Type til application/xml, ved CIM JSON er vær- dien application/json.

For at indikere hvilket format man ønsker svaret leveret i sættes Accept. Her kan man vælge imellem application/xml og application/json. Undlades værdien bliver der som default sendt et svar via application/json.

 Hvis indholdet overholder de gældende regler, vil der blive returneret 202 Accepted fra Data- Hub. Når dette returneres, vil der ikke være noget indhold med i svaret. Ved eventuelle sup- port henvendelser kan man referere til værdien der findes i http-headeren CorrelationId, denne kan bruges til at spore forespørgslen i DataHub.

POST /v1.0/cim/RequestEndOfSupply HTTP/1.1

Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Accept: application/json

Content-Type: application/xml

Content-Length: <content-length-of-request>

<? xml version=”1.0” encoding=”UTF-8” ?>

...

HTTP/1.1 202 Accepted

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

2.1.2      HTTP GET

Når man vil hente data ud fra DataHub dannes der en GET-forespørgsel. For at indikere det for- mat man ønsker svaret returneret i sættes Accept headeren. DataHub vil forsøge at leve op til den ønskede værdi. Der understøttes umiddelbart to værdier application/xml og applica- tion/json. DataHub vil i svaret indikere det faktiske indholds format ved at sætte Content-Type til enten application/xml eller application/json.

Serveren vil svare tilbage med det indhold der er fundet på forespørgslen. Hvis der er et doku- ment, vil statuskoden være 200 OK, hvis der ikke er fundet noget indhold, vil statuskoden være 204 No Content.

GET /v1.0/cim/timeseries HTTP/1.1

Host: api.itlev.datahub.dk Authorization: Bearer <bearer-token>

Accept: application/xml

Svar uden indhold:

HTTP/1.1 204 No Content

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

Svar med indhold:

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: <content-length-of-response>

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

MessageId: <id-of-message>

<? Xml version=”1.0” encoding=”UTF-8” ?>

...

2.1.3      HTTP DELETE

Skal der fjernes noget indhold fra DataHub benyttes en DELETE-forespørgsel. Serveren kan svare tilbage med to forskellige statuskoder, 200 OK hvis det lykkedes at gennemføre fore- spørgslen. Ved fejl se fejlbeskeder i sektion 2.3. Ved at sætte Accept kan man indikere hvilket format man ønsker svaret returneret i.

DELETE /v1.0/cim/deqeueue/<id-of-message> HTTP/1.1

Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Accept: application/json

Positiv tilbagemelding:

HTTP/1.1 200 OK

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

Negativ tilbagemelding:

HTTP/1.1 400 Bad Request

Content-Type: application/json

Content-Length: <content-length-of-response>

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

{

   ”error”: {

      ”code”: ”BadArgument”,
      ”message”: ”Unknown message-id”,
      ”target”: ”message-id”,
      ”innererror”: {

         ”code”: ”MessageIdNotKnown”,
         ”message-id”: ”<id-of-message>”
      }
   }

}

2.2       Sikkerhed

For at kommunikere med CIM kanalen er en krypteret forbindelse påkrævet. DataHub udstiller en HTTPS-adresse hvor alt kommunikation skal foregå.

Udover den krypterede forbindelse gør DataHub brug af OAuth til at sikre identiteten af aktø- ren. Dette sker ved at aktøren medsender et bearer token for hvert kald. For at hente et token – se afsnit 2.6.

Bearer token skrives i et http-header, Authorization, hvor det prefixes med Bearer.

POST /v1.0/cim/RequestEndOfSupply

HTTP/1.1 Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Content-Type: application/xml

Content-Length: <content-length-of-request>

<?xml version=”1.0” encoding=”UTF-8”?>

<RequestEndOfSupply_MarketDocument>

...

</RequestEndOfSupply_MarketDocument>

2.3       Validering af forespørgsler

Der bliver foretager flere valideringer når en forespørgsel håndteres af DataHub. Hver af disse valideringer kan resultere i forskellige fejl koder.

Hvis der er en fejl ved forespørgslen, bliver fejlen beskrevet ved hjælp af en ”fejl” datastruktur.

Se nedenstående tabeller. Strukturen kan returneres enten som XML eller JSON alt efter hvad klienten har indikeret i Accept header feltet. Hvis feltet ikke er medsendt, vil der som standard blive svaret i JSON.

ErrorResponse : object

Error : object

InnerError : object

2.4       HTTP endpoints

Der udstilles en adresse til hvert af de dokumenttyper man kan udveksle med DataHub.

2.5       Identifikation af besked type

For at hente et dokument fra DataHub sker det via en GET-kanal. Hver kanal kan returnere én eller flere dokumenttyper. Den pågældende dokumenttype kan læses fra http-headeren MessageType. For en komplet liste af dokumenttyper der kan modtages, kan dette ses i appendix – Dokumenttype og deres relation til kø’er

2.6       Azure B2C – Oauth

OAuth 2.0 [RFC 6749] er et rammeværk, der muliggør tredjeparts adgang til beskyttet HTTP endpoints. Den OAuth metode der benyttes i DataHub 3 er Client Credentials Grant, som er en metode der oftest benyttes til server-til-server kommunikation.

Nedenstående diagram viser forløbet, når en aktør trækker en JWT token og benytter denne til at kalde DataHubs API i forbindelse med aktørtesten, der påbegyndes i februar 2022. Nedenstående kald tager udgangspunkt i ping-endpoint'et i ovenstående tabel.

Bearer token trækkes via et POST:

Path: 20e7a6b4-86e0-4e7a-a34d-6dc5a75d1982/oauth2/v2.0/token HTTP/1.1

Host: login.microsoftonline.com/

Content-Type: application/x-www-form-urlencoded

Content-Length: 185

grant_type=client_credentials&client_id=client_id_provided_by_energinet&scope=54ff4628-ddb1-41ad-9fb0-60286da90d87%2F.default&client_secret=client_secret_provided_by_energinet

HTTP-kaldets body skal bestå af følgende key-value pairs.

Positiv tilbagemelding:

{

   "token_type": "Bearer",

   "expires_in": 3599,

   "ext_expires_in": 3599,

   "access_token": " <bearer-token>"

}

Negativ tilbagemelding

{

  "error": <Fejlkode til at klassifisere fejltyper og reagere på dem>,

  "error_description": <Fejlmeddelelse til at identificere root cause>,

  "error_codes": [<Liste af STS-specifikke fejlkoder>],

  "timestamp": <Tidspunktet for hvornår fejlen opstod>,

  "trace_id": <Unikt ID for forespørgslen til fejlfinding>,

  "correlation_id": <Unikt ID for forespørgslen>,

  "error_uri": <link til hvor information om fejltypen findes>

}