fastapi-xroad-soap 0.4.2

FastAPI Extension for X-Road SOAP

FastAPI X-Road SOAP

Description

By convention until now, creating a well-working SOAP service has been a difficult undertaking due to the inherent complexity of the SOAP specification, which is further exacerbated by the constraints and requirements of the X-Road data-exchange ecosystem. This library remediates this issue by providing excellent batteries-included developer experience for solving the most complex tasks related to the subject. Creating an X-Road SOAP service does not have to be difficult or time-consuming ever again.

Features

• Extension of FastAPI, which integrates well with the existing FastAPI ecosystem
• Definition of requests and responses using ORM-like models syntax
• Automatic validation of request and response elements and data types
• Automatic WSDL file generation from defined models
• Support for sync and async endpoint handlers
• Built-in endpoint for serving the generated WSDL file
• Built-in Fault response error messages
• Excellent pytest coverage and code quality
• Plentiful examples and documentation
• Developer-oriented ease of use

Quickstart

Install the library from PyPI. We recommend to use the Poetry or the PIP package manager:

poetry add fastapi-xroad-soap

pip install fastapi-xroad-soap

Note 1: You also need to install an ASGI web server library like Uvicorn to run the SoapService FastAPI app.
Note 2: You also need a third-party application for making HTTP requests. The most widely used application for testing SOAP services is SoapUI by SmartBear, but you can also use any other software like Postman or Insomnia. The main requirement for the software is that it must support setting custom request headers and making HTTP POST requests with raw body content.

Next, create an example.py file with the following contents:

import uvicorn
from fastapi_xroad_soap import SoapService, MessageBody
from fastapi_xroad_soap.elements import Integer

soap = SoapService()

class Model(MessageBody):
    number = Integer()

@soap.action("ReturnInteger")
def handler(body: Model) -> Model:
    return Model(number=body.number)

uvicorn.run(soap)

This simple service just returns the integer from the client request back to the client. When you run the script and navigate to http://localhost:8000/service?wsdl in your web browser, you should see the generated WSDL file that corresponds to the SoapService instance.

Making a Request

If you're using SoapUI for API testing, it is suggested to import the autogenerated WSDL file of the service into SoapUI, as that will enable SoapUI to autogenerate example requests for the defined services and skip the manual setting of the necessary HTTP headers, you just need to fill in the placeholders with valid values. In other cases, read on how to manually craft a valid request for the example service.

In your chosen API testing software, create a new POST request and set the following custom headers:

1. Key: SOAPAction, Value: ReturnInteger
2. Key: Content-Type, Value: text/xml

Set the following XML as the raw body and send the request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <Model>
            <Number>1234</Number>
        </Model>
    </soapenv:Body>
</soapenv:Envelope>

You should receive the following response if everything is working as expected:

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <Model>
            <Number>1234</Number>
        </Model>
    </soapenv:Body>
</soapenv:Envelope>

Next Steps

1. Try out the other examples in the examples directory.
2. Read the full documentation and API reference in the Wiki.
3. Build something awesome with this library!

Credits

Centre of Registers and Information Systems