Working with SOAP based Web Service using Python | by AYUSHI SHARMA | Medium

Basic usage

Version: API^3^

The sudsClient class provides a consolidated API for consuming web services.
The object contains (2) sub-namespaces:

service:: The
service namespace provides a proxy for the consumed service. This
object is used to invoke operations (methods) provided by the service
endpoint.

factory:: The
factory namespace provides a factory that may be used to create
instances of objects and types defined in the WSDL.

You will need to know the url for WSDL for each service used. Simply
create a client for that service as follows:

You can inspect service object with: __str()__ as follows to get a
list of methods provide by the service:

printclientSuds-version: 0.3.3build: (beta) R397-20081121Service (WebServiceTestBeanService) tns="http://test.server.enterprise.rhq.org/"Prefixes (1):
     ns0="http://test.server.enterprise.rhq.org/"Ports (1):
     (Soap)
       Methods:
         addPerson(Personperson, )
         echo(xs:stringarg0, )
         getList(xs:stringstr, xs:intlength, )
         getPercentBodyFat(xs:stringname, xs:intheight, xs:intweight)
         getPersonByName(Namename, )
         hello()
         testExceptions()
         testListArg(xs:string[] list, )
         testVoid()
         updatePerson(AnotherPersonperson, namename, )
   Types (23):
     PersonNamePhoneAnotherPerson

note: See example of service with multiple ports below.

The sample output lists that the service named
WebServiceTestBeanService has methods such as
getPercentBodyFat() and addPerson().

Complex arguments

The addPerson() method takes a person argument of type:
Person and has a signature of: addPerson(Person person,
) where parameter type is printed followed by it’s name. There is a
type (or class) named ‘person’ which is coincidentally the same name
as the argument.

So, to create a Person object to pass as an argument we need to
get a person argument using the factory sub-namespace as
follows:

As you can see, the object is created as defined by the WSDL. The list
of phone number is empty so we’ll have to create a Phone
object:

… and the name (Name object) and age need to be set and we need to
create a name object first:

Now, let’s set the properties of our Person object

It’s that easy.

Complex arguments using python (dict)

Note: version 0.3.8

Just like the factory example, let’s assume the addPerson() method
takes a person argument of type: Person. So, to create a
Person object to pass as an argument we need to get a person
object and we can do so by creating a simple python dict.

According to the WSDL we know that the Person contains a list of Phone
objects so we’ll need dicts for them as well.

… and the name (Name object) and age need to be set and we need to
create a name object first:

Now, let’s set the properties of our Person object

… and invoke our method named addPerson() as follows:

Content-type

В наши дни большинство API-интерфейсов используют в качестве типа контента по умолчанию JSON.

Вернувшись к одному из предыдущих примеров использования TheDogAPI, мы заметим, что заголовокContent-Typeопределен какapplication/json:

Custom soap headers

Custom SOAP headers may be passed during the service invocation by using
the soapheadersoption. A custom soap header is defined as a header that is
required by the service by not defined in the wsdl.

Do not try to pass the header as an XML string such as:

It will not work because: 1. Only
Elements are processed as custom headers. 1. The XML string
would be escaped as <ssn:SessionID>123</ssn:SessionID>
anyway.

*Notes: 1. Passing single
Elements as soap headers fixed in Ticket #232 (r533) and will be
released on 0.3.7. 1. Reusing this
Element in subsequent calls fixed in Ticket #233 (r533) and will be
released on 0.3.7.

Doctors

The
Doctor class provides the interface for classes that provide this
service. Once defined, the doctor can be specified using the
schema doctor as an
option when creating the Client. Or, you can use one of the stock
doctors

• ImportDoctor – Used to fix import problems. For example:

Documentplugin

The DocumentPlugin currently has (2) hooks::

loaded() :: Called before parsing a WSDL or XSD
document. The context contains the url & document text.

parsed() :: Called after parsing a WSDL or XSD
document. The context contains the url & document root.

Enumerations

Enumerations are handled as follows:

Let’s say the wsdl defines the following enumeration:

The client can instantiate the enumeration so it can be used. Misspelled
references to elements of the enum will raise a AttrError
exception as:

Factory

The
factory is used to create complex objects defined the the wsdl/schema.
This is not necessary for parameters or types that are specified
as simple types such as xs:string, xs:int, etc …

The create() method should always be used becuase it returns objects
that already have the proper structure and schema-type information.
Since xsd supports nested type definition, so does create() using the
(.) dot notation. For example suppose the (Name) type was not defined as
a top level “named” type but rather defined within the (Person) type.

If the type is in the same namespace as the wsdl (targetNamespace) then
it may be referenced without any namespace qualification. If not, the
type must be qualifed by either a namespace prefix such as:

Or, the name can be fully qualified by the namespace itself using the
full qualification syntax as (as of 0.2.6):

Qualified names can only be used for the first part of the
name, when using (.) dot notation to specify a path.

Features

Basic features:

• No class generation
• Provides an object-like API.
• Reads wsdl at runtime for encoding/decoding
• Provides for the following SOAP (style) binding/encoding:
• Document/Literal
• RPC/Literal
• RPC/Encoded (section 5)

Logging

The suds package use the Python standard lib logging package:
all messages are at level DEBUG or ERROR.

To register a console handler you can use basicConfig:

Message injection (diagnostics/testing)

The service API provides for message/reply injection.

To inject either a soap message to be sent or to inject a reply or fault
to be processed as if returned by the soap server, simply specify the
__inject keyword argument with a value of a dictionary
containing either:

• msg = <message string>
• reply = <reply string>
• fault = <fault string>

when invoking the service. Eg:

Sending a raw soap message:

Injecting a response for testing:

Method 1: using request

First, we import requests library, then we define the SOAP URL. 

The next and the most important step is to format the XML body according to the structure provided in the SOAP URL. To know the format, simply visit the SOAP URL and click on CountryISOCode link and format the XML accordingly.

Then you simply prepare the headers and make the POST call.

Code:

Output:

Multi-document (document/literal)

In most cases, services defined using the document/literal SOAP binding
style will define a single document as the message payload. The
<message/> will only have (1) <part/> which references an
<element/> in the schema. In this case, suds presents a RPC view of
that method by displaying the method signature as the contents (nodes)
of the document. Eg:

Suds will report the method foo signature as:

This provides an RPC feel to the document/literal soap binding style.

Now, if the wsdl defines:

Suds will be forced to report the method foo signature as:

The message has (2) parts which defines that the message payload
contains (2) documents. In this case, suds must present a /Document/
view of the method.

Overview

Suds is a lightweight SOAP-based web service client for Python
licensed under LGPL (see the LICENSE.txt file included in the
distribution).

Although the original suds package stopped releasing versions after 0.4,
many (but not all) other open source projects moved to a maintained fork known
as “suds-jurko”. This is a community fork of that fork that is releasing
packages under the main suds package name (and suds-community for
consistency until version 2.x of this package).

Forked project information

Original suds Python library development project information

For development notes see the HACKING.rst document included in the
distribution.

Proxies

The suds default
transport handles proxies using urllib2.Request.set_proxy(). The
proxy options can be passed set using Client.set_options. The proxy
options must contain a dictionary where keys=protocols and values are
the hostname (or IP) and port of the proxy.

Python soap client, authorization

class HRDConfig {
    public $uid = "__partner_uid__";
    public $pass = "__encoded_cspNr_and_pass__"; // ie. "csp123pass"

    const NS = "https://www.hrd.pl/partnerAPI/";
    const PARTNER = "https://www.hrd.pl/partnerAPI/Partner.php?wsdl";
    const DOMAIN = "https://www.hrd.pl/partnerAPI/Domain.php?wsdl";
    const CERTIFICATE = "https://www.hrd.pl/partnerAPI/Certificate.php?wsdl";
    const CLIENT = "https://www.hrd.pl/partnerAPI/Client.php?wsdl";
    const POLL = "https://www.hrd.pl/partnerAPI/Poll.php?wsdl";
    const INVOICE = "https://www.hrd.pl/partnerAPI/Invoice.php?wsdl";
}

ini_set("soap.wsdl_cache_enabled", "1"); //enable cache
$soap = new SoapClient(HRDConfig::DOMAIN, array("encoding"=>"UTF-8", "exceptions" => true));
$soap->__setSoapHeaders(array(new SoapHeader(HRDConfig::NS, "AuthHeader", new HRDConfig())));

Python support

See .github/workflows/test_and_release.yml for supported Python versions. The goal is to support
currently maintained versions of Python.

Python3

Request и response

Все взаимодействия между клиентом (в нашем случае консолью Python) и API разделены на запрос (request) и ответ (response):

• requestсодержит данные запроса API: базовый URL, конечную точку, используемый метод, заголовки и т. д.
• responseсодержит соответствующие данные, возвращаемые сервером, в том числе контент, код состояния и заголовки.

Снова обратившись к TheDogAPI, мы можем немного подробнее рассмотреть, что именно находится внутри объектовrequestиresponse:

Requests и api

При использовании API с Python нам понадобится всего одна библиотека:requests. С её помощью вы сможете выполнять бо́льшую часть, если не все, действия, необходимые для использования любого общедоступного API.

Установите библиотеку любым удобным вам способом, например, с помощью pip:

python3 -m pip install requests

Чтобы следовать примерам кода из руководства, убедитесь, что вы используете Python не ниже 3.8 и версию библиотекиrequestsне ниже 2.22.0.

Services with multiple ports

Some services are defined with multiple ports as:

And are reported by suds as:

This example only has (1) method defined for each port but it could very
likely have may methods defined. Suds does not require the method
invocation to be qualifed (as shown above) by the port as:

Simple arguments

Let’s start with the simple example. The getPercentBodyFat() method has
the signature of getPercentBodyFat(xs:string name,
xs:int height, xs:int weight). In this case, the
parameters are simple types. That is, they not objects. This
method would be invoked as follows:

Soap vs rest vs graphql

В конце 1990-х и начале 2000-х годов две разные модели дизайна API стали нормой для публичного доступа к данным:

1. SOAP(Simple Object Access Protocol) ассоциируется с корпоративным миром, имеет строгую систему на основе «контрактов». Этот подход в основном связан скорее с обработкой действий, чем с данными.
2. REST(Representational State Transfer) используется для общедоступных API и идеально подходит для получения данных из интернета.

Ssl certificate verification & custom certificates

With Python 2.7.9, SSL/TLS verification is turned on by default.

This can be a problem when suds is used against an endpoint which has a self-signed certificate, which is quite common in the corporate intranet world.

One approach to turn off certificate validation in suds is to use a custom transport class. For example in Python 3:

In addition, if a custom set of certificates and/or root CA is needed, this can also be done via a custom transport class. For example, in Python 3:

class ClientHttpsTransport(HttpTransport):
    def __init__(self, certfile, keyfile, cafile, *args, **kwargs):
        super(ClientHttpsTransport, self).__init__(*args, **kwargs)
        self.certfile = certfile
        self.keyfile = keyfile
        self.cafile = cafile

    def u2handlers(self):
        handlers = super(ClientHttpsTransport, self).u2handlers()
        context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=self.cafile)
        context.load_cert_chain(self.certfile, self.keyfile)
        context.check_hostname = False
        context.verify_mode = ssl.CERT_NONE
        handlers.append(urllib.request.HTTPSHandler(context=context))
        return handlers

custom_https = ClientHttpsTransport('/path/to/certificate_file', '/path/to/key_file', '/path/to/ca_file')

client = Client(url, transport=custom_https),

Suds-py3¶

Suds is a lightweight SOAP python client that provides a
service proxy for Web Services.

#!pythonprintclientSuds-version:1.3.3.1build:IN20220220Service(WebServiceTestBeanService)tns="http://test.server.enterprise.rhq.org/"Prefixes(1):ns0="http://test.server.enterprise.rhq.org/"Ports(1):(Soap)Methods:addPerson(Personperson,)echo(xs:stringarg0,)getList(xs:stringstr,xs:intlength,)getPercentBodyFat(xs:stringname,xs:intheight,xs:intweight)getPersonByName(Namename,)hello()testExceptions()testListArg(xs:string[]list,)testVoid()updatePerson(AnotherPersonperson,namename,)Types(23):PersonNamePhoneAnotherPerson

Timeouts

Per request timeouts can be set by using a __timeout keyword argument in
each call. This supersedes the global client default. For example, the
following call will have a timeout of 10 seconds:

Wsdl with multiple services & multiple ports

version: 0.3.7

Some WSDLs define multiple services which may (or may not) be defined
with multiple ports as:

And are reported by suds as:

This example only has (1) method defined for each port but it could very
likely have may methods defined. Suds does not require the
method invocation to be qualifed (as shown above) by the service and/or
port as:

Аутенфикация

Хотя многие API бесплатны и полностью общедоступны, аутентификация обычно существенно расширяет права доступа. Существует множество API, требующих аутентификации, например:

Подходы к аутентификации варьируются от очень простых, например, использования ключей API или базовой аутентификации, до гораздо более сложных и безопасных методов, таких как OAuth.

Как правило, вызов API без учетных данных или с некорректной учетной записью возвращают коды состояний401 Unauthorizedили403 Forbidden.

Запрос наиболее популярных сейчас гифок

Как насчет создания небольшого скрипта, который извлекает три самых популярных сейчас GIF-файла с веб-сайтаGIPHY? Начните сполучения API-ключа:

1. Создайте аккаунт наGIPHY
2. Перейдите впанель разработчикаи зарегистрируйтеновое приложение.
3. Получите ключ для соединения с API.

Ключ API используем в GIPHY API:

Знакомство с api

АббревиатураAPIсоответствует английскому application programming interface — программный интерфейс приложения. По сути, API действует как коммуникационный уровень или интерфейс, который позволяет различным системам взаимодействовать друг с другом без необходимости точно понимать, что делает каждая из систем.

Изучение продвинутых концепций api

Теперь, когда у нас есть представление об основах использования API с Python, есть несколько более сложных тем, которые стоит хотя бы кратко затронуть: аутентификация, пагинация и ограничения по времени.

Использование api с помощью python: практические примеры

Теперь, когда мы поэкспериментировали с несколькими API, можно объединить полученные знания с помощью еще нескольких практических примеров.

Ключи api

Самый распространенный подход к аутентификации — это ключ API (API key). Эти ключи используются для идентификации вас как пользователя или клиента API, а также для отслеживания использования вами интерфейса. Ключи API обычно отправляются как заголовок запроса или как параметр запроса.

В этом примере мы воспользуемся API-интерфейсом NASAMars Rover Photo APIи получим снимки, сделанные 1 июля 2020 года. В целях тестирования вы можете использовать ключ APIDEMO_KEY, который НАСА предоставляет по умолчанию.

Чтобы добавить в свой запрос ключ API, укажите параметр запросаapi_key=.

Конечные точки и ресурсы

Как мы видели выше, первое, что нужно знать для использования API, — это базовый URL-адрес API. Вот так выглядят базовые URL-адреса нескольких известных провайдеров API:

Ограничение скорости

Учитывая, что рассматриваемые API-интерфейсы являются общедоступными и могут использоваться кем угодно, ими пытаются злоупотреблять люди с плохими намерениями. Чтобы предотвратить такие атаки, используется метод, называемый ограничением скорости (rate limit).

Некоторые API, такие как GitHub, даже включают в заголовки дополнительную информацию о текущем ограничении скорости и количестве оставшихся запросов. Это очень помогает избежать превышения установленного лимита.

Пагинация

За пересылку большого массива данных между клиентами и сервером приходится платить пропускной способностью. Для снижения нагрузки на сервер API-интерфейсы обычно используют пагинацию — разбиение выдаваемой информации на страницы.

Например, всякий раз, когда мы переходим на страницу вопросов в Stack Overflow, внизу страницы есть ряд чисел, соответствующих страницам пагинации:

В API пагинация обычно обрабатывается с помощью двух параметров запроса:

1. Атрибутpageопределяет номер запрашиваемой страницы
2. Атрибутsizeопределяет размер каждой страницы

Параметры запроса

Иногда при вызове API можно получить тонну данных, которые в массе своей не нужны. При вызове конечной точкиTheDogAPI/breedsмы получаем всю информацию о каждой породе, но вполне вероятно, что нам достаточно лишь небольшой части данных для одного подвида собак. Тут пригождаются параметры запроса!

Поиск в google книгах

Воспользуемся API Google Книг для поиска информации об интересующей нас книге. Вот простой фрагмент кода для поиска названия книгиМоби Дикво всем каталоге с выдачей трех первых записей:

Получение подтвержденных случаев covid-19 в каждой стране

API сайта, отслеживающего случаи заболевания COVID-19, не требует аутентификации. В следующем примере мы получим общее количество подтвержденных случаев до предыдущего дня:

Пользовательские заголовки

Еще один стандарт, с которым вы можете столкнуться при использовании API,— использование настраиваемых заголовков. Обычно они начинаются с префиксаX-. Разработчики API обычно используют настраиваемые заголовки для отправки или запроса дополнительной информации от клиентов.

Для определения заголовков можно использовать словарь, передаваемый в методrequests.get(). Например, предположим, что вы хотите отправить некоторый идентификатор запроса на сервер API и знаете, что можете сделать это с помощьюX-Request-Id:

Initplugin

The InitPlugin currently has (1) hook:

initialized() :: Called after the client is initialized. The
context contains the WSDL object.

Initializing optional arrays with lists

In some unreleased versions of suds-jurko, all children elements were populated with empty lists. This was fixed in suds-community as a regression. This can be desired behavior as it simplifies constructing complex requests. To obtain the prior behavior, use a custom Builder class, for example:

Заключение

Есть множество других вещей, которые вы ещё узнаете об API: другие заголовки, типы контента, методы аутентификации и так далее. Однако концепции и методы, которые мы рассмотрели в этом руководстве, позволят достаточно быстро разобраться и провзаимодействовать с помощью Python с любыми API.

Напоследок приведем список агрегаторов ссылок на публичные API, которые вы можете использовать в собственных проектах:

***