Service

Request mapping-API

De access token moet aan de request-header van de API-call worden toegevoegd om de gegevens te kunnen opvragen.

Figuur 2: Schematische weergave mappingService.

Endpoint en method

Het endpoint voor het aanroepen van de mapping-API is:

https://mapping.sivi.org/api/mapping

De mapping-API bestaat uit een POST method met het bericht in de body.

Payload

De payload voor de mapping-API is als volgt samengesteld:

{
	"commonFunctional": {
		"entityType": "default",
		"mappingType": ""
	},
	"document": {
		"entityType": "default",
		"content":""
	}
}

Hierbij moet de gewenste mapping type worden ingevuld, bijvoorbeeld AFD1_AFD2:

“mappingType”: “AFD1_AFD2”

De beschikbare mappingen worden op de SIVI website gepubliceerd.

Het bericht wat door de mapping-API omgezet dient te worden, moet eerst gecodeerd worden naar een base64-document. Dit base64-document kan dan in de body geplaatst worden:

“content”: “”

De totale body ziet er dan bijvoorbeeld als volgt uit:

{
	"commonFunctional": {
		"entityType": "default",
		"mappingType": "AFD1_AFD2"
	},
	"document": {
		"entityType": "default",
		"content":"RGl0IGlzIGVlbiBiYXNlNjQtZG9jdW1lbnQu"
	}
}

Response mapping-API

Bij een succesvolle mapping wordt de HTTP status 200 geretourneerd met een response-bericht.

Lay-out response-bericht:

{
   "commonTechnical":    {
      "entityType": "default",
      "applicationVersion": ""
   },
   "commonFunctional":    {
      "entityType": "default",
      "mappingType": ""
   },
   "document":    {
      "entityType": "default",
      "content": ""
   }
}

De response ziet er dan bijvoorbeeld als volgt uit:

{
"commonTechnical":    {
      "entityType": "default",
      "applicationVersion": "1.1-3.4.1"
   },
	"commonFunctional": {
		"entityType": "default",
		"mappingType": "AFD1_AFD2"
	},
	"document": {
		"entityType": "default",
		"content":"RGl0IGlzIGVlbiBiYXNlNjQtZG9jdW1lbnQu"
	}
}

Bij een foutmelding kunnen de volgende HTTP statussen terugkomen:

• 400 Bad Request
  • Het request-bericht is ongeldig / heeft een ongeldige opmaak.
  • De gevraagde mappingType is niet bekend/beschikbaar.
  • Content bevat geen geldig base64-document.
• 401 Unauthorized
  • Autorisatie token is niet geldig of verlopen.
• 404 Not Found
  • De resource (URL) die is opgegeven is niet beschikbaar.
• 412 precondition Failed
  • Het om te zetten bericht is van ander formaat dan verwacht (bijvoorbeeld AFD1.0 wordt niet in XML aangeleverd bij mappingType “AFD1_AFD2”).
• 422 Unprocessable entity
  • Er is een fout opgetreden bij de mapping zelf. Mogelijk oorzaak kan een ongeldig te mappen bericht zijn.

De foutmeldingen worden voorzien van extra informatie om de fout zo duidelijk mogelijk te omschrijven. In enkele gevallen (als de foutmelding geen onderdeel is van de RFC7231) kunnen niet alle attributen gevuld worden, deze worden dan weggelaten.

De volledige lay-out van het error-bericht is als volgt:

{
    "type": [Een URL link naar RFC3986 die het probleemtype beschrijft],
    "title": [Een korte, leesbare samenvatting van het probleemtype],
    "status": [De HTTP-statuscode volgens RFC7231, gegenereerd door de oorspronkelijke server],
    "detail": [Een leesbare uitleg die specifiek is voor dit optreden van het probleem],
    "traceId": [Een uniek nummer waarmee dit probleem ook wordt gelogd in Application Insights],
    "errors": [Array met errors welke de fout hebben veroorzaakt]
}

Een voorbeeld van een foutmelding:

{
   "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
   "title": "Bad Request",
   "status": 400,
   "detail": "The Document attribute doesn't contain a valid base64 string.",
   "traceId": "00-f6086574240f61032146160c62d49697-cd4f780f20998488-00"
}

Versienummer

Het response-bericht bevat een versienummer voor de software die het proces van de mapping verzorgt en de mapping de gebruikt is:

applicationVersion

Gecodeerd bericht

Het omgezette bericht staat in het response-bericht als een base64-document (content). Dit base64-document moet nog worden gedecodeerd om het omgezette bericht in het juiste formaat te krijgen.