Beschrijving waardelijst koppelvlakbeschrijving

Inleiding

Deze instructie bevat de beschrijving van de interface van de waardelijst service (Engels: "reference code service" of kortweg "refcode service"). De reference code service is een REST (REpresentational State Transfer) service die lijsten van referentiecodes uit de BRO-database haalt en retourneert in JSON (JavaScript Object Notation) formaat.

De refrentiecodes zijn noodzakelijk voor de gebruikers van de BRO (denk hierbij aan dataleveranciers en softwareleveranciers) bij het samenstellen en interpreteren van inname- en uitgifteverzoeken. De service wordt ontsloten door de Landelijke Voorziening BRO (LV BRO).

Gegevensmodel

Het gegevensmodel voor BRO waardelijsten bestaat uit een aantal entiteiten:

• domain
  de waardelijst; deze kan met een naam of urn worden geïdentificeerd (b.v. urn:bro:gar:ParameterList)
• domainVersion
  een versie van een waardelijst; deze bestaat uit een hoofd- en subversie (b.v. 1.0)
• code
  een element van een waardelijst; de code is uniek binnen (de versie van) de waardelijst
• attribute
  voor (een versie van) een waardelijst kunnen naast de code/beschrijving ook aanvullende eigenschappen worden gedefinieerd; de GAR ParameterList is hier een voorbeeld van: behalve de codes bevat deze waardelijst ook aquo codes, CAS nummers, etc.
• attributeValue
  een waarde voor een aanvullende eigenschap

Endpoints

De reference code service heeft 5 endpoints:

• get_domains - haalt alle waardelijsten op (zonder de bijbehorende versies, codes en attributen) die in de LV BRO bekend zijn,
• get_domain_versions - haalt alle versies van een waardelijst op (zonder de bijbehorende codes en attributen) die van een specifiek domein in de LV BRO gedefinïeerd zijn,
• get_codes - haalt alle referentie codes op voor één specifieke versie of alle versies van een waardelijst,
• get_attributes - haalt alle attributen (zonder de attribuut waardes) op voor één specifieke versie of alle versies van een waardelijsten
• get_attribute_values - haalt alle attribuut waardes op voor één specifieke versie of alle versies van een waardelijst,

Endpoint

De refcode service is toegankelijk via: https://publiek.broservices.nl in de productieomgeving van de BRO. Dit is de <host> parameter die in hoofdstuk 2 gebruikt wordt.

De endpoints worden in het volgende hoofdstuk in meer detail beschreven. De resultaten van de endpoints zijn beschreven in het laatste hoofdstuk.

Meer informatie

Voor vragen, suggesties of opmerkingen over de inhoud van dit document kunt u contact opnemen met de BRO Servicedesk. Bel 088 – 8644 999 of mail naar support@broservicedesk.nl.
Of kijk voor meer informatie op www.basisregistratieondergrond.nl.

Aanroepen

get_domains

Haal alle in de LV BRO bekende domeinen op. De versies van het domein en de referentiecodes die bij een versie behoren worden niet opgehaald. Optioneel kan een prefix worden gespecificeerd waaraan de naam of urn moet voldoen.

GET <host>/refcodes/api/get_domains[?prefix=<nameOrUrnPrefix>]

waar:

• <nameOrUrnPrefix> - prefix waaraan de naam of de urn van het domein moet voldoen. Voorbeeld: prefix=BHR, prefix=urn:bro:gmw

get_domain_versions

Haal alle in de LV BRO bekende versies van een domein op.

GET <host>/refcode/api/get_domain_versions?domain=<domainNameOrUrn>

waar:

• <domainNameOrUrn> -de naam of urn van het domein. Voorbeeld: domain=urn:bhr:CodeGroup, domain=BHR_CODE_GROUP

get_codes

Haal alle in de LV BRO bekende codes op van één specifieke versie, de meest recente versie of, als geen versie wordt gespecificeerd, alle versies van een domein. 

GET <host>/refcodes/api/get_codes?domain=<domainNameOrUrn>[&version=<version>|latest]

waar:

• <domainNameOrUrn> - de name of urn van het domein. Voorbeeld: domain=urn:bhr:CodeGroup, domain=BHR_CODE_GROUP
• <version> - het versienummer van het domein. Het versienummer bestaat uit een hoofd- en subversienummer, van elkaar gescheiden door een punt. De meest recente versie van een domein kan worden opgehaald door 'latest' te specificeren voor de versie. Voorbeeld: version=1.0, version=latest
  
  

get_attributes

Haal alle in de LV BRO bekende attributen op van één specifieke versie, de meest recente versie of, als geen versie wordt gespecificeerd, alle versies van een domein. 

GET <host>/refcodes/api/get_attributes?domain=<domainNameOrUrn>[&version=<version>|latest]

waar:

• <domainNameOrUrn> - de name of urn van het domein. Voorbeeld: domain=urn:bro:gar:ParameterList, domain=BHRGT_ParameterList
• <version> - het versienummer van het domein. Het versienummer bestaat uit een hoofd- en subversienummer, van elkaar gescheiden door een punt. De meest recente versie van een domein kan worden opgehaald door 'latest' te specificeren voor de versie. Voorbeeld: version=1.0, version=latest

get_attribute_values

Haal alle in de LV BRO bekende attribuut waardes op van één specifieke versie, de meest recente versie of, als geen versie wordt gespecificeerd, alle versies van een domein. 

GET <host>/refcodes/api/get_attribute_values?domain=<domainNameOrUrn>[&version=<version>|latest]

waar:

• <domainNameOrUrn> - de name of uri van het domein. Voorbeeld: domain=urn:bro:gar:ParameterList, domain=BHRGT_ParameterList
• <version> - het versienummer van het domein. Het versienummer bestaat uit een hoofd- en subversienummer, van elkaar gescheiden door een punt. De meest recente versie van een domein kan worden opgehaald door 'latest' te specificeren voor de versie. Voorbeeld: version=1.0, version=latest

Resultaten

Status

De service retourneert een 200 - OK status behalve wanneer:

• een verplichte query parameter ontbreekt of wanneer een ongeldige query parameter waarde wordt gespecificeerd; in dit geval wordt een 400 - Bad Request status geretourneerd,
• geen resultaten gevonden worden die aan de query parameters voldoen; in dat geval wordt een 204 - No Content status geretourneerd.

get_domains

Het get_domains verzoek levert een lijst van domein identificaties (name, uri en description) op. Als geen resultaten worden gevonden die aan de query parameters voldoen, wordt een lege lijst geretourneerd.

{
	"refDomains": [
	    {
        	"name": "BHR_ANOMALOUS_GW_REGIME",
       	 	"uri": "urn:bro:bhr:AnomalousGroundwaterRegime",
        	"description": "Afwijkend grondwater regime"
    	},
    	{
        	"name": "BHR_BORING_STANDARD",
        	"uri": "urn:bro:bhr:BoringStandard",
        	"description": "Boorstandaard"
   	 	},
    	...
	] 
}

get_domain_versions

Het get_domain_versions verzoek levert in een domein met een lijst van versies (major version, minor version en description) op. Als geen resultaat wordt gevonden dat aan de query parameters voldoet, wordt een leeg element geretourneerd.

{
    "name": "BHR_CODE_GRP",
    "uri": "urn:bro:bhr:CodeGroup",
    "refDomainVersions": [
        {
            "majorVersion": 0,
            "minorVersion": 9,
            "description": "Version 0.9"
        },
        {
            "majorVersion": 1,
            "minorVersion": 0,
            "description": "version 1.0"
        },
        ...
    ]
}

get_codes

Het get_codes verzoek levert een domein met een lijst van versies en de daarbij behorende codes (code, imbo, imbroA en description) op. Als geen resultaat wordt gevonden dat aan de query parameters voldoet, wordt een leeg element geretourneerd.

{
    "name": "BHR_GT_SPECIAL_MATERIAL",
    "uri": "urn:bro:bhrgt:SpecialMaterial",
    "refDomainVersions": [
        {
            "majorVersion": 1,
            "minorVersion": 0,
            "refCodes": [
                {
                    "code": "asVulkanisch",
                    "imbro": "J",
                    "imbroA": "J",
                    "description": "Natuurlijk materiaal: vulkanisch materiaal met een korrelgrootte kleiner dan 4 mm."
                },
                {
                    "code": "betonOngebroken",
                    "imbro": "J",
                    "imbroA": "J",
                    "description": "Antropogeen materiaal: beton dat niet als puin wordt geclassificeerd, bijvoorbeeld een betonplaat."
                },
                ...
		},
        ...
	]
}

get_attributes

Het get_attributes verzoek levert een domein met een lijst van versies en de daarbij behorende attributen (name en description) op. Als geen resultaat wordt gevonden dat aan de query parameters voldoet, wordt een leeg element geretourneerd.

{
    "name": "GAR_PARAMETER_LIST",
    "uri": "urn:bro:gar:ParameterList",
    "refDomainVersions": [
        {
            "majorVersion": 1,
            "minorVersion": 0,
            "refAttributes": [
                {
                    "name": "id",
                    "description": "Het ID van de parameter zoals uitgegeven door het SIKB. Dit is een persistent, identificerend volgnummer binnen de referentielijst. Voor nieuwe stoffen kan een nieuwe aquocode met een nieuw ID worden aangevraagd."
                },
                {
                    "name": "aquoCode",
                    "description": "Aquo code."
                },
                {
                    "name": "casNumber",
                    "description": "CAS nummer."
                },
                ...
		},
        ...
	]
}

get_attribute_values

Het get_attribute_values verzoek levert een domein met een lijst van versies, de daarbij behorende codes en de daarbij behorende attribuut waardes (name, value) op. Als geen resultaat wordt gevonden dat aan de query parameters voldoet, wordt een leeg element geretourneerd.

{
    "name": "GAR_PARAMETER_LIST",
    "uri": "urn:bro:gar:ParameterList",
    "refDomainVersions": [
        {
            "majorVersion": 1,
            "minorVersion": 0,
            "refCodes": [
				{
                    "code": "1556",
                    "description": "thiocynaat (anion)",
                    "refAttributeValues": [
                    	{
                    		"name": "aquoCode",
                    		"value": "toCN"
                		},
                    	{
                    		"name": "casNumber",
                    		"value": "463-56-9"
                		},
                		...
					]
				},
				{
                    "code": "1561",
                    "description": "thiometon",
                    "refAttributeValues": [
                    	{
                    		"name": "aquoCode",
                    		"value": "tomtn"
                		},
                    	{
                    		"name": "casNumber",
                    		"value": "640-15-3"
                		}
					]
				},
        		...
			]
		}
	]
}