# FastAPI X-Road SOAP
<img src="https://raw.githubusercontent.com/rik-ee/fastapi-xroad-soap/main/media/fxs_logo.jpg" alt="Logo" width="500">
[](https://pypi.org/project/fastapi-xroad-soap/)
[](https://github.com/rik-ee/fastapi-xroad-soap/actions/workflows/build-publish.yaml)
[](https://codecov.io/gh/rik-ee/fastapi-xroad-soap)
[](https://pypistats.org/packages/fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)<br/>
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)
[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-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](https://x-road.global/) 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](https://pypi.org/project/fastapi-xroad-soap/). We recommend to use the [Poetry](https://python-poetry.org/) or the [PIP](https://pip.pypa.io/en/stable/) package manager:
```shell
poetry add fastapi-xroad-soap
```
```shell
pip install fastapi-xroad-soap
```
_**Note 1:**_ You also need to install an ASGI web server library like [Uvicorn](https://www.uvicorn.org/) 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](https://www.soapui.org/tools/soapui/) by SmartBear, but
you can also use any other software like [Postman](https://www.postman.com/downloads/) or [Insomnia](https://insomnia.rest/download).
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:
```python
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:
```xml
<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
<?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](https://github.com/rik-ee/fastapi-xroad-soap/tree/main/examples) directory.
2) Read the full documentation and API reference in the [Wiki](https://github.com/rik-ee/fastapi-xroad-soap/wiki).
3) Build something awesome with this library!
### Credits
[Centre of Registers and Information Systems](https://www.rik.ee/en)
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-xroad-soap",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "fastapi, xroad, soap",
"author": "Zero Reports Team",
"author_email": "zero.dev@rik.ee",
"download_url": "https://files.pythonhosted.org/packages/eb/e6/9c0a544ed07cf1547f5ec6369b8c3caefbbfe51d402c063f5b79d8119e00/fastapi_xroad_soap-0.4.2.tar.gz",
"platform": null,
"description": "# FastAPI X-Road SOAP\n\n<img src=\"https://raw.githubusercontent.com/rik-ee/fastapi-xroad-soap/main/media/fxs_logo.jpg\" alt=\"Logo\" width=\"500\">\n\n\n[](https://pypi.org/project/fastapi-xroad-soap/)\n[](https://github.com/rik-ee/fastapi-xroad-soap/actions/workflows/build-publish.yaml)\n[](https://codecov.io/gh/rik-ee/fastapi-xroad-soap)\n[](https://pypistats.org/packages/fastapi-xroad-soap)\n\n\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)<br/>\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n[](https://sonarcloud.io/summary/new_code?id=rik-ee_fastapi-xroad-soap)\n\n\n### Description\n\nBy convention until now, creating a well-working SOAP service has been a difficult undertaking due to the inherent complexity \nof the SOAP specification, which is further exacerbated by the constraints and requirements of the [X-Road](https://x-road.global/) data-exchange ecosystem. \nThis library remediates this issue by providing excellent batteries-included developer experience for solving the most complex tasks related to the subject. \nCreating an X-Road SOAP service does not have to be difficult or time-consuming ever again. \n\n\n### Features\n\n- Extension of FastAPI, which integrates well with the existing FastAPI ecosystem\n- Definition of requests and responses using ORM-like models syntax\n- Automatic validation of request and response elements and data types\n- Automatic WSDL file generation from defined models\n- Support for sync and async endpoint handlers\n- Built-in endpoint for serving the generated WSDL file\n- Built-in Fault response error messages\n- Excellent pytest coverage and code quality\n- Plentiful examples and documentation\n- Developer-oriented ease of use\n\n\n### Quickstart\n\n\nInstall the library from [PyPI](https://pypi.org/project/fastapi-xroad-soap/). We recommend to use the [Poetry](https://python-poetry.org/) or the [PIP](https://pip.pypa.io/en/stable/) package manager: \n\n```shell\npoetry add fastapi-xroad-soap\n```\n```shell\npip install fastapi-xroad-soap\n```\n\n_**Note 1:**_ You also need to install an ASGI web server library like [Uvicorn](https://www.uvicorn.org/) to run the SoapService FastAPI app. \n_**Note 2:**_ You also need a third-party application for making HTTP requests. The most widely used application for testing SOAP services is [SoapUI](https://www.soapui.org/tools/soapui/) by SmartBear, but \nyou can also use any other software like [Postman](https://www.postman.com/downloads/) or [Insomnia](https://insomnia.rest/download). \nThe main requirement for the software is that it must support setting custom request headers and making HTTP POST requests with raw body content. \n\nNext, create an `example.py` file with the following contents:\n```python\nimport uvicorn\nfrom fastapi_xroad_soap import SoapService, MessageBody\nfrom fastapi_xroad_soap.elements import Integer\n\nsoap = SoapService()\n\nclass Model(MessageBody):\n number = Integer()\n\n@soap.action(\"ReturnInteger\")\ndef handler(body: Model) -> Model:\n return Model(number=body.number)\n\nuvicorn.run(soap)\n```\n\nThis simple service just returns the integer from the client request back to the client. \nWhen you run the script and navigate to `http://localhost:8000/service?wsdl` in your web browser, \nyou should see the generated WSDL file that corresponds to the `SoapService` instance.\n\n\n### Making a Request\n\nIf you're using SoapUI for API testing, it is suggested to import the autogenerated WSDL file of the service \ninto SoapUI, as that will enable SoapUI to autogenerate example requests for the defined services and skip the \nmanual setting of the necessary HTTP headers, you just need to fill in the placeholders with valid values. \nIn other cases, read on how to manually craft a valid request for the example service. \n\nIn your chosen API testing software, create a new POST request and set the following custom headers: \n1) Key: `SOAPAction`, Value: `ReturnInteger`\n2) Key: `Content-Type`, Value: `text/xml`\n\nSet the following XML as the raw body and send the request: \n```xml\n<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Body>\n <Model>\n <Number>1234</Number>\n </Model>\n </soapenv:Body>\n</soapenv:Envelope>\n```\n\nYou should receive the following response if everything is working as expected:\n```xml\n<?xml version='1.0' encoding='utf-8' standalone='yes'?>\n<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Body>\n <Model>\n <Number>1234</Number>\n </Model>\n </soapenv:Body>\n</soapenv:Envelope>\n```\n\n### Next Steps\n\n1) Try out the other examples in the [examples](https://github.com/rik-ee/fastapi-xroad-soap/tree/main/examples) directory. \n2) Read the full documentation and API reference in the [Wiki](https://github.com/rik-ee/fastapi-xroad-soap/wiki). \n3) Build something awesome with this library!\n\n\n### Credits\n\n[Centre of Registers and Information Systems](https://www.rik.ee/en)\n\n",
"bugtrack_url": null,
"license": "EUPL-1.2",
"summary": "FastAPI Extension for X-Road SOAP",
"version": "0.4.2",
"project_urls": {
"Bug Tracker": "https://github.com/rik-ee/fastapi-xroad-soap/issues",
"Documentation": "https://github.com/rik-ee/fastapi-xroad-soap/wiki",
"Repository": "https://github.com/rik-ee/fastapi-xroad-soap"
},
"split_keywords": [
"fastapi",
" xroad",
" soap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c3cb6f314c03654b579b2d4e7a373a65891bf99adc6016f95ddc1805663307b",
"md5": "2e45997f94ce219667914da7da3e9337",
"sha256": "97aa33a461fe784d9010f0bba08af5f94553cf02e4f9b6736657bd82addf4b50"
},
"downloads": -1,
"filename": "fastapi_xroad_soap-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e45997f94ce219667914da7da3e9337",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 70976,
"upload_time": "2024-04-25T18:43:12",
"upload_time_iso_8601": "2024-04-25T18:43:12.480539Z",
"url": "https://files.pythonhosted.org/packages/0c/3c/b6f314c03654b579b2d4e7a373a65891bf99adc6016f95ddc1805663307b/fastapi_xroad_soap-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ebe69c0a544ed07cf1547f5ec6369b8c3caefbbfe51d402c063f5b79d8119e00",
"md5": "4cb88eb0231213c7bcd9002860a71caf",
"sha256": "18380c5edf7692039c2f9b1eae8f777c70476020a001d8f6bdd8e808e2bf856c"
},
"downloads": -1,
"filename": "fastapi_xroad_soap-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "4cb88eb0231213c7bcd9002860a71caf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 38663,
"upload_time": "2024-04-25T18:43:15",
"upload_time_iso_8601": "2024-04-25T18:43:15.064127Z",
"url": "https://files.pythonhosted.org/packages/eb/e6/9c0a544ed07cf1547f5ec6369b8c3caefbbfe51d402c063f5b79d8119e00/fastapi_xroad_soap-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 18:43:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rik-ee",
"github_project": "fastapi-xroad-soap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastapi-xroad-soap"
}
JSON
