Skip to content

REST API

Jump to bottom
Philip Helger edited this page Sep 4, 2024 · 8 revisions

REST API introduction

The key element of the SMP is its predefined REST API. See the Peppol SMP specification for details on the intention of the REST URL paths. Only two reading REST API are specified, all others are implementation specific.

phoss SMP also supports the Peppol Directory specification for providing Business Cards.

Modifying calls

Some of the APIs presented here require user credentials to work. All modifying REST APIs are either using HTTP PUT or HTTP DELETE for creating/updating or for deleting elements.

As the SMP itself running without transport security these modifying methods require the use of HTTP Bearer Token or Basic Auth - see below.

Note: all writing REST APIs can be disabled in the configuration file using the smp.rest.writableapi.disabled property (since 4.0.2). See Configuration for details. Since version 5 the writable API can also be enabled or disabled in the settings of the GUI.

Authorization

Bearer Token [preferred] (since v6.0.7)

As HTTP Basic Auth requires to send nearly a plain text password as part of the HTTP transmission the Bearer Token is an alternative.

The Bearer Token to be used can be created in the Administration interface in the page "Administration | Security | User Tokens". Each User Token is uniquely assigned to a user and can hence be used to execute actions on this users behalf. The benefit of the User Token is, that it can ONLY be used for the API. The token can not be used to login to the user interface. Each token can easily be revoked or recreated in case a token got compromised.

The HTTP header Authorization MUST be used with the Bearer scheme like shown in the following example:

Authorization: Bearer your-token-here

Basic Auth [old-style]

To send an HTTP Basic Auth you must provide an HTTP header called Authorization with a value like created by the following pseudo code:

"Basic " + Base64.encode (email + ":" + password)

Please see the page on Security how to handle BasicAuth in a proper and secure way.

Service Group API

  • GET /{ServiceGroupId} or GET /bdxr-smp-2/{ServiceGroupId} (only when using the REST Type bdxr2)
    Description: Get a list of all document types supported by this particular Service Group. This is one of the mandatory APIs
    Authentication: none

  • GET /complete/{ServiceGroupId}
    Description: Get a list of all document types and endpoints supported by this particular Service Group.
    Authentication: none

  • PUT /{ServiceGroupId}
    URL parameters:

    • Optionally you can use create-in-sml=false to not create a service group in the SML (since v5.4.0)

    Expected body: A ServiceGroupType object as specified by the SMP XSD.
    Description: create a new service group. All endpoints must be specified - this method does not add new endpoints, but overwrite all existing endpoints.
    Authentication: this function requires Authentication

    Example body (Peppol style):

    <smp:ServiceGroup xmlns:smp="http://busdox.org/serviceMetadata/publishing/1.0/" xmlns:id="http://busdox.org/transport/identifiers/1.0/">
  <id:ParticipantIdentifier scheme="iso6523-actorid-upis">9876:participantid</id:ParticipantIdentifier>
  <smp:ServiceMetadataReferenceCollection/>
</smp:ServiceGroup>

    Example body (OASIS BDXR SMP v1 style):

    <smp:ServiceGroup xmlns:smp="http://docs.oasis-open.org/bdxr/ns/SMP/2016/05">
  <smp:ParticipantIdentifier scheme="iso6523-actorid-upis">9876:participantid</smp:ParticipantIdentifier>
  <smp:ServiceMetadataReferenceCollection/>
</smp:ServiceGroup>

  • DELETE /{ServiceGroupId}
    URL parameters:

    • Optionally you can use delete-in-sml=false to not delete a service group in the SML (since v5.4.0)

    Expected body: none
    Description: Delete the whole service group with the specified service group ID. Implicitly deletes all related elements as well.
    Authentication: this function requires Authentication

Service Metadata API

  • GET /{ServiceGroupId}/services/{DocumentTypeId} or GET /bdxr-smp-2/{ServiceGroupId}/services/{DocumentTypeId} (only when using the REST Type bdxr2)
    Description: Get a list of all endpoints supported by this particular Service Group for the provided document type ID. This is one of the mandatory APIs. is implemented in the com.helger.phoss.smp.rest.APIExecutorServiceMetadata* classes. The signature is added directly inside the respective methods.
    Authentication: none

  • PUT /{ServiceGroupId}/services/{DocumentTypeId}
    Expected body: A ServiceMetadataType object as specified by the SMP XSD.
    Description: Define the AP endpoint URL etc. for a certain participant and a certain document type.
    Note: This will overwrite all existing processes and endpoints for this participant and document type!
    Authentication: this function requires Authentication

    Example body (Peppol style):

    <smp:ServiceMetadata xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:smp="http://busdox.org/serviceMetadata/publishing/1.0/" xmlns:id="http://busdox.org/transport/identifiers/1.0/">
  <smp:ServiceInformation>
    <id:ParticipantIdentifier scheme="iso6523-actorid-upis">9876:participantid</id:ParticipantIdentifier>
    <id:DocumentIdentifier scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1</id:DocumentIdentifier>
    <smp:ProcessList>
      <smp:Process>
        <id:ProcessIdentifier scheme="cenbii-procid-ubl">urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</id:ProcessIdentifier>
        <smp:ServiceEndpointList>
          <smp:Endpoint transportProfile="peppol-transport-as4-v2_0">
            <wsa:EndpointReference>
              <wsa:Address>http://test.smpserver/as4</wsa:Address>
            </wsa:EndpointReference>
            <smp:RequireBusinessLevelSignature>false</smp:RequireBusinessLevelSignature>
            <smp:Certificate>blacert</smp:Certificate>
            <smp:ServiceDescription>Unit test service</smp:ServiceDescription>
            <smp:TechnicalContactUrl>https://github.com/phax/phoss-smp</smp:TechnicalContactUrl>
          </smp:Endpoint>
        </smp:ServiceEndpointList>
      </smp:Process>
    </smp:ProcessList>
  </smp:ServiceInformation>
</smp:ServiceMetadata>

    Example body (OASIS BDXR SMP v1 style):

    <smp:ServiceMetadata xmlns:smp="http://docs.oasis-open.org/bdxr/ns/SMP/2016/05">
  <smp:ServiceInformation>
    <smp:ParticipantIdentifier scheme="iso6523-actorid-upis">9876:participantid</smp:ParticipantIdentifier>
    <smp:DocumentIdentifier scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1</smp:DocumentIdentifier>
    <smp:ProcessList>
      <smp:Process>
        <smp:ProcessIdentifier scheme="cenbii-procid-ubl">urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</smp:ProcessIdentifier>
        <smp:ServiceEndpointList>
          <smp:Endpoint transportProfile="peppol-transport-as4-v2_0">
            <smp:EndpointURI>http://test.smpserver/as4</smp:EndpointURI>
            <smp:RequireBusinessLevelSignature>false</smp:RequireBusinessLevelSignature>
            <smp:Certificate>YmxhY2VydA==</smp:Certificate>
            <smp:ServiceDescription>Unit test service</smp:ServiceDescription>
            <smp:TechnicalContactUrl>https://github.com/phax/phoss-smp</smp:TechnicalContactUrl>
          </smp:Endpoint>
        </smp:ServiceEndpointList>
      </smp:Process>
    </smp:ProcessList>
  </smp:ServiceInformation>
</smp:ServiceMetadata>

  • DELETE /{ServiceGroupId}/services/{DocumentTypeId}
    Expected body: none.
    Description: Delete all participant information for the specified document type
    Authentication: this function requires Authentication

  • DELETE /{ServiceGroupId}/services (since v5.2.4)
    Expected body: none.
    Description: Delete all Endpoints and Redirects of the participant
    Authentication: this function requires Authentication

Business Card API - basis for Peppol Directory

  • GET /businesscard/{ServiceGroupId}
    Description: Get the Business Card associated to the provided service group. This is one of the mandatory APIs.
    Authentication: none

  • PUT /businesscard/{ServiceGroupId} (since v5.0.2)
    Expected body: A business card in XML format as defined by the Peppol Directory Business Card XSD. See https://docs.peppol.eu/edelivery/ or https://github.com/phax/peppol-commons/tree/master/peppol-directory-businesscard/src/main/resources/schemas - currently all 3 versions are supported.
    Description: Create or update the business card of the specified service group
    Authentication: this function requires Authentication

    Example body:

    <BusinessCard xmlns="http://www.peppol.eu/schema/pd/businesscard/20180621/">
  <ParticipantIdentifier scheme="iso6523-actorid-upis">9876:participantid</ParticipantIdentifier>
  <BusinessEntity>
    <Name language="en">Test entity</Name>
    <CountryCode>AT</CountryCode>
    <Identifier scheme="iso6523-actorid-upis">12345678912</Identifier>
  </BusinessEntity>
</BusinessCard>

  • DELETE /businesscard/{ServiceGroupId} (since v5.0.2)
    Expected body: none.
    Description: Delete the business card of the specified service group
    Authentication: this function requires Authentication

  • POST /businesscard/{ServiceGroupId}/push (since v7.1.5)
    Expected body: none.
    Description: explicitly push a business card to the configured Directory
    Authentication: this function requires Authentication

Migration API - migrating participants from and to the SMP

This set of REST APIs was introduced in v5.6.0 to ease migrations.

  • PUT /migration/outbound/start/{ServiceGroupId}
    Description: Start the outbound migration of the provided Service Group ID
    Authentication: this function requires Authentication
    Output: specific XML containing success and the created migration key. In case of error, an HTTP status error code is returned.
    Example success XML message:
<?xml version="1.0" encoding="UTF-8"?>
<migrationOutboundResponse success="true">
    <participantID>iso6523-actorid-upis::0000:demo</participantID>
    <migrationKey>abcdef123456</migrationKey>
</migrationOutboundResponse>

  • PUT /migration/outbound/cancel/{ServiceGroupId}
    Description: Cancel the outbound migration of the provided Migration ID - one of the results of the "start" call. Cancel aborts the migration. See ".../finalize/..." for the successful finish.
    Authentication: this function requires Authentication
    Output: none

  • PUT /migration/outbound/finalize/{ServiceGroupId}
    Description: Finalize the outbound migration of the provided Migration ID - one of the results of the "start" call. Successfully finishes the migration. This API will delete the Service Group on this SMP. See ".../cancel/..." for the unsuccessful abortion.
    Authentication: this function requires Authentication
    Output: none

  • PUT /migration/inbound/{ServiceGroupId}/{MigrationKey}
    Description: Perform the inbound migration of the provided Service Group ID using the provided Migration Key (mind the correct masking of the value). This will perform the migration in the SMK/SML, create the Service Group in the SMP and remember the migration details. This step takes over the responsibility for the Service Group and the DNS change has been done.
    Authentication: this function requires Authentication
    Output: some rudimentary XML details on success

  • PUT /migration/inbound
    Description: Perform the inbound migration of the provided Service Group ID using the provided Migration Key (mind the correct masking of the value). This will perform the migration in the SMK/SML, create the Service Group in the SMP and remember the migration details. This step takes over the responsibility for the Service Group and the DNS change has been done.
    This function is specifically designed to ease the migration from phoss SMP to phoss SMP.
    Body: the XML layout as created from /migration/outbound/start/
    Authentication: this function requires Authentication
    Output: some rudimentary XML details on success

Exchange API - import and export of data

This set of REST APIs was introduced in v5.6.0 to improve ease of data handling.

  • Export Service Groups

    • GET /exchange/export/all/xml/v1
      Description: Export all Service Groups to XML format v1.
      URL parameters:

      • include-business-cards (type: boolean, default: true if Directory integration is enabled) - if enabled, the business cards will be part of the exported data.

      Authentication: this function requires Authentication
      Output: SMP export XML
      Error codes:

      • 403 if the authentication header is missing or ill-formed

    • GET /exchange/export/byowner/{UserId}/xml/v1
      Description: Export all Service Groups owned by the specified user to XML format v1.
      Path parameters:

      • {UserId} the login name of the user to export the data from. Must match the user name of the Authentication user name.

      URL parameters:

      • include-business-cards (type: boolean, default: true if Directory integration is enabled) - if enabled, the business cards will be part of the exported data.

      Authentication: this function requires Authentication.
      Output: SMP export XML
      Error codes:

      • 403 if the authentication header is missing or ill-formed
      • 403 if {UserId} does not match the user from authentication

    • GET /exchange/export/specific/{ServiceGroupId}/xml/v1
      Description: Export the specific Service Group to XML format v1.
      Path parameters:

      • {ServiceGroupId} the fully qualified identifier of the Service Group to export.

      URL parameters:

      • include-business-cards (type: boolean, default: true if Directory integration is enabled) - if enabled, the business cards will be part of the exported data.

      Authentication: this function requires Authentication.
      Output: SMP export XML
      Error codes:

      • 400 if {ServiceGroupId} is in an invalid format
      • 403 if the authentication header is missing or ill-formed
      • 404 if no such Service Group is contained

    • GET /exchange/export/outboundmigip/xml/v1
      Description: Export all Service Groups that are part of an running outbound migration with state "in progress" to XML format v1.
      URL parameters:

      • include-business-cards (type: boolean, default: true if Directory integration is enabled) - if enabled, the business cards will be part of the exported data.

      Authentication: this function requires Authentication
      Output: SMP export XML
      Error codes:

      • 403 if the authentication header is missing or ill-formed

    • PUT /exchange/import/xml/v1/{UserId}
      Expected body: The output of a previous SMP data export in XML format v1.
      Description: Import all Service Groups and Business cards contained in the provided XML format v1.
      Path parameters:

      • {UserId} the login name of the user that becomes the owner of the new records. May differ from the one used in Authentication.

      URL parameters:

      • overwrite-existing (type: boolean, default: false) - if enabled, all Service Groups already existing in the SMP will be overwritten. Service Group overwriting means, deletion of the old Service Group and creation of a new one.

      Authentication: this function requires Authentication
      Output: the action log of the import in an XML format
      Error codes:

      • 400 if {UserId} refers to an unknown or deleted user
      • 400 if the provided data cannot be read as XML
      • 400 if the provided XML format uses the wrong version
      • 403 if the authentication header is missing or ill-formed
      • 412 if the writable REST API is disabled

Remote Query API

This set of REST APIs was introduced to use the SMP as a single source for all SMP matters. It was introduced in version 5.3.0-RC2.

Note: This set of APIs always uses the same API for querying as it is configured for. So if the SMP is running in "Peppol" mode, all SMP queries will also be in "Peppol" mode. This is currently not customizable.

Note: This set of APIs always uses the same SML configuration as it is configured for. So if your SMP is configured to use SMK, you can only query other SMK entries. This is currently not customizable.

Note: this set of APIs is disabled by default, to avoid that arbitrary users can use this API to DDOS other SMP servers. To enable these APIs, the configuration property smp.rest.remote.queryapi.disabled must be set to false.

  • Query remote document types
    • GET /smpquery/{ServiceGroupId}
      Description: query a list of all document types of a participant from a remote SMP
    • URL parameters:
      • businessCard (type: boolean, default: false) - if enabled, the business card of the service group is also queried
      • xmlSchemaValidation (type: boolean, default: true) - if enabled, the SMP response is validated against the underlying XML schema
  • Query remote ServiceMetadata
    • GET /smpquery/{ServiceGroupId}/{DocumentTypeId}
    • URL parameters:
      • xmlSchemaValidation (type: boolean, default: true) - if enabled, the SMP response is validated against the underlying XML schema
      • verifySignature (type: boolean, default: true) - if enabled, the digital signature of the SMP response is validated (recommended). If this is disabled, the security is heavily degraded.
  • Query remote BusinessCards
    • GET /businesscardquery/{ServiceGroupId}
    • URL parameters: none

It is appreciated if you star the GitHub project if you like it.

Donation link: https://paypal.me/PhilipHelger

Logo

Clone this wiki locally