The basics

CoreConcept

The API service works by sending an authenticated POST request to the primary API endpoint. This request contains an XML-encoded ApiRequest that describes the actions to be processed. The response will be an XML or ZIP file containing the result data and any continuation actions, if applicable.

Refer to the reference sections for guidance on programmatic usage and how to integrate the API service into your application. The code snippets in the authentication examples section may serve as a good starting point.

The following paragraphs provide examples of how to explore the API service.

Interactive Exploration

Import the following configurations into your Postman, Thunder Client, or EchoAPI application:
- Environment
- Collection
Adjust the idpUsername and idpPassword variables in the Environment
Adapt and execute the predefined requests in the Collection

One-off Scripting with PowerShell

First, we need a function to authenticate and obtain an access_token for the API service. Remember that tokens are only valid for a limited time and must be refreshed periodically.

function Get-IpiDataDeliveryToken
{
  param (
    [string] $IdpUsername = $env:IDP_USERNAME,
    [string] $IdpPassword = $env:IDP_PASSWORD
  )
    
  $TOKEN_ENDPOINT="https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
  $PARAMS = @{
    grant_type = "password"
    client_id = "datadelivery-api-client"
    username = $IdpUsername
    password = $IdpPassword
  }
  $res = Invoke-RestMethod -Method Post -Uri $TOKEN_ENDPOINT -ContentType "application/x-www-form-urlencoded" -Body $PARAMS
  return $res.access_token
}

$IdpCredentials = if ($IdpCredentials) { $IdpCredentials } else {
   Get-Credential -Message "Datadelivery IDP Credentials"
}
$env:IDP_USERNAME = $IdpCredentials.UserName
$env:IDP_PASSWORD = $IdpCredentials.GetNetworkCredential().Password
$env:IDP_TOKEN = $(Get-IpiDataDeliveryToken)

Next, we define a helper function that sends authenticated POST requests to the primary API endpoint.

function Invoke-IpiDataDeliveryApi
{
  param (
    [ValidateSet("xml","zip")][String] $Format = "xml",
    [string] $IdpToken = $env:IDP_TOKEN,
    [string] $RequestXml = "<ApiRequest xmlns='urn:ige:schema:xsd:datadeliverycore-1.0.0'/>",
    [switch] $AlwaysFile
  )
    
  $API_ENDPOINT="https://www.swissreg.ch/public/api/v1"
  $PARAMS = @{
    Uri = $API_ENDPOINT;
    Method = 'Post';
    Headers = @{
      Authorization = "Bearer ${IdpToken}";
      Accept = "application/${Format}";
    };
    ContentType = "application/xml";
    Body = $RequestXml;
  }
  if ($PSVersionTable.PSVersion.Major -ge 7)
  {
    $PARAMS += @{
      ResponseHeadersVariable = 'resHdr';
      StatusCodeVariable = 'resStatus'
    }
  }
  if ($AlwaysFile -Or $Format -Eq 'zip')
  {
    $res = New-TemporaryFile
    Invoke-RestMethod @PARAMS -OutFile $res
  } else
  {
    $res = Invoke-RestMethod @PARAMS
  }
  if ($resStatus)
  {
    Write-Information "Status: ${resStatus}"
  }
  if ($resHdr)
  {
    ConvertTo-Json $resHdr | ConvertFrom-Json | Format-List | Out-String | Write-Information
  }
  return $res
}

With these functions in place, we can now send our first ApiRequest to execute a TrademarkSearch action. The API responds with an XML document containing the result of the first page of items satisfying the query. If additional results are available, continuations for subsequent pages will be included as well.

$InformationPreference='Continue'

$res = Invoke-IpiDataDeliveryApi -Format xml -RequestXml @"
<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" xmlns:tm="urn:ige:schema:xsd:datadeliverytrademark-1.0.0">
    <Action type="TrademarkSearch">
        <tm:TrademarkSearchRequest xmlns="urn:ige:schema:xsd:datadeliverycommon-1.0.0">
            <Representation details="Maximal" />
            <Page size="10"/>
            <Query>
                <Any>wasser*</Any>
            </Query>
            <Sort>
                <LastUpdateSort>Descending</LastUpdateSort>
            </Sort>
        </tm:TrademarkSearchRequest>
    </Action>
</ApiRequest>
"@
Write-Output $res.InnerXml

Alternatively, responses can be delivered as a ZIP bundle. This format contains the same information but compressed within a ZIP archive. The result items and/or, optionally, their associated resources (e.g. images) and item facets can be split into separate files within the archive by specifying Bundle as the ResourceAction in the Representation element.

Delivering responses as a ZIP bundle offers several benefits. It reduces Response Data Transfer Quota consumption, as the data is compressed. Additionally, it simplifies data extraction and processing for the client. Having a ZIP archive with pre-split components allows clients to access and manipulate individual files directly, rather than parsing through a large XML document containing items from different namespaces.

$InformationPreference='Continue'

$resZip = Invoke-IpiDataDeliveryApi -Format zip -RequestXml @"
<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" xmlns:tm="urn:ige:schema:xsd:datadeliverytrademark-1.0.0">
    <Action type="TrademarkSearch">
        <tm:TrademarkSearchRequest xmlns="urn:ige:schema:xsd:datadeliverycommon-1.0.0">
            <Representation details="Default" images="Bundle">
                <Resource role="item" action="Bundle" />
            </Representation>
            <Page size="5"/>
            <Query>
                <Require>
                    <tm:FeatureCategory>Combined</tm:FeatureCategory>
                </Require>
            </Query>
            <Sort>
                <LastUpdateSort>Descending</LastUpdateSort>
            </Sort>
        </tm:TrademarkSearchRequest>
    </Action>
</ApiRequest>
"@
Move-Item -Path $resZip -Destination "result_$(Get-Date -Format FileDateTime).zip" -PassThru