Central IAL
The Central IAL is the component created by WP5 to implement the Issuing Authority Locator functionality defined by WP3.
This chapter describes the big picture of the IAL implementation, based on Business Cards provided in a decentralised way through the DE4A Directory.
The above figure shows the relationships of the different components. The blue SMP instances are already existing and are representing pilot partners SMP instances. These SMPs need to provide Business Cards to a centralised Directory. This Directory is an existing piece of software (based on the original Peppol Directory) which offers a standardized REST API for querying. This REST API will be used by the IAL Proxy Service, which in turn offers the public API as described in chapter to any DR.
The benefit of this setup is, that pilots can maintain the data decentralised in their SMPs. This data is automatically copied (replicated) into the central Directory where a complete index of all Business Cards from all SMPs is available for centralised querying. The Directory offers only a read-only API to non-SMPs, so there can never be a data update from the Directory to an SMP.
Data Owner queries
This chapter groups all the queries that can be used to query Data Owners (DOs). This functionality is called DSD (Data Services Directory) in TOOP and SDG-OOP.
/provision/{canonicalObjectTypeIDs}[/{atuCode}] API
Get all Data Owners that support the requested canonical object types. If an administrative territorial unit (ATU) is provided, it will also be taken into account.
Note: URLs are limited to 2048 characters. Therefore, only a maximum of 20 canonical object type IDs are safely supported.
Note: this API provides no special handling for the multi evidence case. It will only return the canonical evidence object types it was queried for.
Compatibility note: this interface replaces the following interfaces present in Iteration 1:
/ial/{canonicalEvidenceTypeId}
/ial/{canonicalEvidenceTypeId}/{countryCode}
The old APIs allowed only one canonical evidence type ID and optionally only a country code. This is a breaking change but can easily be hidden from implementers by keeping the Connector query API unchanged.
URL parameters:
- {canonicalObjectTypeIDs} – mandatory – one or more canonical object type identifiers, including the identifier schemes. Multiple IDs need to be separated by the comma (,) character. A maximum of 20 different values is allowed.
- {atuCode} – optional – an administrative territorial unit (ATU) code on an arbitrary level. This can be a country code, a NUTS 1, a NUTS 2, a NUTS 3 or a LAU code. If no ATU code is provided, results from all regions will be returned.
Query parameters:
none
Request body:
none
Response body:
An XML document of type ResponseLookupRoutingInformationType (as defined by IAL.xsd). If nothing is found, this is indicated in this response. If the Accept HTTP header favours “application/json” over “application/xml”, a JSON representation will be returned.
Status codes:
- HTTP 200 Success: If the message was processed correctly
- HTTP 400 Bad Request: If the request payload does not match the requirements (e.g. invalid parameters)
- HTTP 500 Internal Server Error: If something unexpected happened
Examples calls (non-normative):
The examples are displayed without URL encoding. In reality e.g. all “:” characters must be replaced with “%3A” to work.
- /provision/urn:de4a-eu:CanonicalEvidenceType::CompanyRegistration:1.0
Search for all EPs that support the “Company Registration” evidence type, independent of the country
- /provision/urn:de4a-eu:CanonicalEvidenceType::CompanyRegistration:1.0/AT
Search for all EPs that support the “Company Registration” evidence type, limit to the matches in Austria
- /provision/urn:de4a-eu:CanonicalEvidenceType::CompanyRegistration:1.0/AT130
Search for all EPs that support the “Company Registration” evidence type, limit to the matches in Vienna, Austria (NUTS 3)
- /provision/urn:de4a-eu:CanonicalEvidenceType::MarriageRegistration:1.0,urn:de4a-eu:CanonicalEvidenceType::BirthCertificate:1.0
Search for all EPs that support the “Marriage Registration” or the “Birth Certificate” evidence type, independent of the country
- · /provision/urn:de4a-eu:CanonicalEvidenceType::MarriageRegistration:1.0,urn:de4a-eu:CanonicalEvidenceType::BirthCertificate:1.0/SE
Search for all EPs that support the “Marriage Registration” or the “Birth Certificate” evidence type, limit to the matches in Sweden