SOAP service testing: Difference between revisions

Revision as of 13:11, 15 June 2012

Krediidiinfo AS SOAP service is tested using curl software and the KiCompany service. Other Krediidiinfo AS SOAP services can also be tested in the same way.

Authentication is possible using the certificate/key pair as well as the HTTP Basic Authentication user name and password. In addition to the password or certificate, the user needs to have been issued a permission to use the KiCompany service by Krediidiinfo AS customer service.

If the following tests in the client's environment are successful, it can be stated that the certificate or password issued to the client is valid, and the permissions to use KiCompany are correctly set.

Network test

The request's source environment must be able to connect to the services.krediidiinfo.ee server using the tcp port number 443. Krediidiinfo AS has not set any IP-based limitations to that server.

The netcat utility can be used in order to test whether there is a firewall blocking the connection:

nc -z -vv services.krediidiinfo.ee 443

In some operating systems the binary has a different name:

netcat -z -vv services.krediidiinfo.ee 443

The positive result would be:

Connection to services.krediidiinfo.ee 443 port [tcp/https] succeeded!

Examples of negative results:

nc: connect to services.krediidiinfo.ee port 443 (tcp) failed: Connection refused

nc: connect to services.krediidiinfo.ee port 443 (tcp) failed: Connection timed out

Also it should be possible to connect to the tcp port 80, of the same server, which hosts the wsdl files and this wiki. If the test fails, please contact your network administrator

SOAP request example

First of all we must know the name of the service to be requested. In this example we use the KiCompany service, so the request URI would be https://services.krediidiinfo.ee/soap.php?name=KiCompany.

Next we need the SOAP request itself, which is kept in a text file named data.txt, The contents of the file are as follows:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <m:findCompanies xmlns:m="urn:KiCompany" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <name xsi:type="xsd:string">kredi</name>
      <count xsi:type="xsd:int">2</count>
    </m:findCompanies>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This request searches for companies with names that starts with kredi and displays only the first two results. (The request involves the payment of a fee!)

Using curl

The command-line tool curl is a convenient testing utility. To use the Krediidiinfo AS SOAP service, curl must be compiled with SSL support and must support https protocol. You can check whether this is the case by using the command curl --version; the result:

curl 7.19.6 (x86_64-redhat-linux-gnu) libcurl/7.19.6 NSS/3.12.4.1 Beta zlib/1.2.3 libidn/0.6.14 libssh2/0.18
Protocols: tftp ftp telnet dict ldap ldaps http file https ftps scp sftp
Features: GSS-Negotiate IDN IPv6 Largefile SSL libz

curl SOAP request, using HTTP Basic Authentication

Krediidiinfo AS has issued you a user name and password. In this example, the user name is "1234" and password is "abc123".

curl -d @data.txt -u 1234:abc123 https://services.krediidiinfo.ee/soap.php?name=KiCompany

-d specifies the request. @ before the file name specifies that it is a request file, not a request.

-u specifies user name and password, delimited with a colon.

curl SOAP request, using a certificate and a key as the authentication method

To make a request you need a certificate file issued by Krediidiinfo AS in the PEM format. In this example the file is named cert.pem. It looks like this:

Also you need a certificate key file in the PEM format, which, in this example, is named key.pem. This is a secret file and must not be transmitted via e-mail or by other unencrypted methods.

However, the contents of this file may be added directly to the cert.pem file (cat key.pem >> cert.pem), thus making it unnecessary to specify the key file for curl. Various programs specifically request such concatenated files. It looks similar to the following example; only the DSA option has some more differences:

Also, in the case of an encrypted key, you must know the certificate key password. The password in this example is abcd1234.

Making a request:

curl -d @data.txt -cert $PWD/cert.pem:abcd1234 --key $PWD/key.pem https://services.krediidiinfo.ee/soap.php?name=KiCompany

-d specifies the request, @ before the file name specifies that it is a request file, not a request.

--cert key specifies the location of certificate file. Absolute path must be used. curl is not looking for the file in given directory, hence the $PWD in the example.

If the key is encrypted, the password can be provided after the certificate file name, separating it from the file name by a colon.

--key determines the location of the key file. It is not necessary, if the certificate and key files are merged into a single file.

This is why the key password is specified with the --cert option, not here.

SOAP request results

Successful request

Successful request (line spacing added for easier reading):

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:KiCompany" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:findCompaniesResponse>
<companies SOAP-ENC:arrayType="ns1:CompanyIDData[2]" xsi:type="ns1:CompanyIDDataArray">
<item xsi:type="ns1:CompanyIDData">
<regCode xsi:type="ns1:regCode">11517686</regCode>
<name xsi:type="xsd:string">KREDICO OÜ</name>
</item>
<item xsi:type="ns1:CompanyIDData">
<regCode xsi:type="ns1:regCode">90006012</regCode>
<name xsi:type="xsd:string">KREDIIDI JA EKSPORDI GARANTEERIMISE SITHASUTUS KREDEX</name>
</item>
</companies>
</ns1:findCompaniesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Invalid requests

Error in GET parameter (KiCompan instead of KiCompany):

curl -d @data.txt -u 1234:abc123 https://services.krediidiinfo.ee/soap.php?name=KiCompan

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Incorrect HTTP GET parameter 'name' value!</faultstring>
<faultactor></faultactor>
<detail>
<errorcode>-20002</errorcode>
<line_no>157</line_no>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Invalid user name, password or certificate:

curl -d @data.txt -u 1234:abZZ23 https://services.krediidiinfo.ee/soap.php?name=KiCompany

Authentication of Krediidiinfo web service user failed! For assistance, please contact Krediidiinfo by calling (+372) 6659600.

User has no permission to use KiCompany please contact our customer service:

curl -d @data.txt -u 1234:abc123 https://services.krediidiinfo.ee/soap.php?name=KiCompany

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Access denied for KiCompany!</faultstring>
<faultactor></faultactor>
<detail>
<errorcode>-20003</errorcode>
<line_no>106</line_no></detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Missing SOAP request:

curl -u 1234:abc123 https://services.krediidiinfo.ee/soap.php?name=KiCompany

(no results)

Error in the SOAP request itself:

curl -d @vigane.txt -u 1234:abc123 https://services.krediidiinfo.ee/soap.php?name=KiCompany

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Bad Request</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

or

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:VersionMismatch</faultcode>
<faultstring>Wrong Version</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

@@ Line 6: / Line 6: @@
-== Võrgu test ==
+== Network test ==
-Keskkond, millest päring tehakse, peab saama ühenduda <tt>services.krediidiinfo.ee</tt> serverisse tcp porti <tt>443</tt>. Krediidiinfo AS poolt ei ole IP põhiseid piiranguid sellele serverile.
+The request's source environment must be able to connect to the <tt>services.krediidiinfo.ee</tt> server using the tcp port number <tt>443</tt>. Krediidiinfo AS has not set any IP-based limitations to that server.
+The <tt>netcat</tt> utility can be used in order to test whether there is a firewall blocking the connection:
-Testimaks, ega mõni tulemüür vahele ei sega võib kasutada programmi <tt>netcat</tt>:
   nc -z -vv services.krediidiinfo.ee 443
-Mõnes operatsioonisüsteemis on binaari nimi teine:
+In some operating systems the binary has a different name:
   netcat -z -vv services.krediidiinfo.ee 443
-Positiivne tulemus on:
+The positive result would be:
   Connection to services.krediidiinfo.ee 443 port [tcp/https] succeeded!
-Näited negatiivsetest tulemustest on:
+Examples of negative results:
   nc: connect to services.krediidiinfo.ee port 443 (tcp) failed: Connection refused
   nc: connect to services.krediidiinfo.ee port 443 (tcp) failed: Connection timed out
-Samuti peaks olema võimalik ühenduda sama serveri tcp porti <tt>80</tt>, kust leiab [http://www.w3.org/TR/wsdl wsdl] failid ning sellesama wiki. Kui test ei õnnestu, tuleks pöörduda oma võrguadministraatori poole.
+Also it should be possible to connect to the tcp port <tt>80</tt>, of the same server, which hosts the [http://www.w3.org/TR/wsdl wsdl] files and this wiki. If the test fails, please contact your network administrator
-== SOAP päringu näide ==
+== SOAP request example ==
-Esiteks peab teadma, mis teenuse pihta päring teha. Antud näites kasutame [[KiCompany]] teenust, seega päringu URI on <tt>https://services.krediidiinfo.ee/soap.php?name=KiCompany</tt>.
+First of all we must know the name of the service to be requested. In this example we use the [[KiCompany_en | KiCompany]] service, so the request URI would be <tt>https://services.krediidiinfo.ee/soap.php?name=KiCompany</tt>.
-Teiseks on vaja SOAP päringut ennast, hoiame seda teksifailis nimega <tt>data.txt</tt>, faili sisu järgnev:
+Next we need the SOAP request itself, which is kept in a text file named <tt>data.txt</tt>, The contents of the file are as follows:
 <pre>
 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
@@ Line 43: / Line 42: @@
 </pre>
-Antud päring otsib firmasid, mis algavad stringiga <tt>kredi</tt> ning ei kuva rohkem kui kaks esimest vastust. (Päring on tasuline!)
+This request searches for companies with names that starts with <tt>kredi</tt> and displays only the first two results. (The request involves the payment of a fee!)
-== curl kasutamine ==
+== Using curl==
-Testimiseks on mugav kasutada käsurea programmi <tt>curl</tt>. Krediidiinfo AS SOAP teenuse kasutamiseks peab <tt>curl</tt> olema kompileeritud SSL toega ning oskama https protokolli. Veenduge selles käsuga <tt>curl --version</tt>, tulemus:
+The command-line tool <tt>curl</tt> is a convenient testing utility. To use the Krediidiinfo AS SOAP service, <tt>curl</tt> must be compiled with SSL support and must support https protocol. You can check whether this is the case by using the command <tt>curl --version</tt>; the result:
   curl 7.19.6 (x86_64-redhat-linux-gnu) libcurl/7.19.6 NSS/3.12.4.1 Beta zlib/1.2.3 libidn/0.6.14 libssh2/0.18
@@ Line 53: / Line 52: @@
   Features: GSS-Negotiate IDN IPv6 Largefile '''SSL''' libz
-=== curl SOAP päring kasutades autentimiseks HTTP Basic Authentication'it ===
+=== curl SOAP request, using HTTP Basic Authentication ===
-Krediidiinfo AS poolt on teile väljastatud kasutajanimi ja parool, siin näites olgu kasutajanimi "1234" ning parool "abc123".
+Krediidiinfo AS has issued you a user name and password. In this example, the user name is "1234" and password is "abc123".
   curl -d @data.txt -u 1234:abc123 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
-  -d määrab päringu. @ märk failinime ees ütleb curl'ile, et tegemist on päringufaili, mitte päringu endaga.
+  -d specifies the request. @ before the file name specifies that it is a request file, not a request.
-  -u määrab kasutaja ja parooli, mis on eraldatud kooloniga.
+  -u specifies user name and password, delimited with a colon.
-=== curl SOAP päring kasutades autentimiseks sertifikaati ja võtit ===
+=== curl SOAP request, using a certificate and a key as the authentication method ===
-Päringu tegemiseks on esiteks vaja Krediidiinfo AS poolt väljasatud sertifikaadi faili PEM formaadis, antud näites on failinimeks <tt>cert.pem</tt>. Välja näeb umbes selline:
+To make a request you need a certificate file issued by Krediidiinfo AS in the PEM format. In this example the file is named <tt>cert.pem</tt>. It looks like this:
 <pre>
 -----BEGIN CERTIFICATE-----
@@ Line 81: / Line 80: @@
-Teiseks sertifikaadi võtme faili PEM formaadis, siin failinimeks <tt>key.pem</tt>. See fail on salajane ning kindlasti emaili teel või muul krüptimata viisil mitte vahendada!
+Also you need a certificate key file in the PEM format, which, in this example, is named <tt>key.pem</tt>. This is a secret file and must not be transmitted via e-mail or by other unencrypted methods.
-Samas võib selle faili sisu otsa liita <tt>cert.pem</tt> failile <tt>(cat key.pem >> cert.pem)</tt>, siis ei pea võtmefaili <tt>curl</tt>'le eraldi ette näitama. Paljud programmid nõuavad just kokku liidetud varianti. Näeb umbes selline välja, DSA variandi puhul on natuke rohkem erinevusi:
+However, the contents of this file may be added directly to the <tt>cert.pem</tt> file <tt>(cat key.pem >> cert.pem)</tt>, thus making it unnecessary to specify the key file for <tt>curl</tt>. Various programs specifically request such concatenated files. It looks similar to the following example; only the DSA option has some more differences:
 <pre>
 -----BEGIN RSA PRIVATE KEY-----
@@ Line 101: / Line 100: @@
 </pre>
-Peab teadma ka sertifikaadi võtme parooli, kui võti on krüpteeritud. Antud näites olgu parool <tt>abcd1234</tt>.
+Also, in the case of an encrypted key, you must know the certificate key password. The password in this example is <tt>abcd1234</tt>.
-Päringu teostamine:
+Making a request:
   curl -d @data.txt -cert $PWD/cert.pem:abcd1234 --key $PWD/key.pem <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
-  -d võti määrab päringu, @ failinime ees ütleb curl'ile, et tegemist on päringufaili, mitte päringu endaga.
+  -d specifies the request, @ before the file name specifies that it is a request file, not a request.
-  --cert võti määrab sertifikaadi faili asukoha. Tuleb kasutada "absolute path"-i. curl ei otsi faili antud kataloogist, seetõttu ka <tt>$PWD</tt> antud näites.
+  --cert key specifies the location of certificate file. Absolute path must be used. curl is not looking for the file in given directory, hence the $PWD in the example.
- Kui võti on krüpteeritud, saab parooli määrata serdifikaadi failinime taga, eraldades selle failinimest kooloniga.
+If the key is encrypted, the password can be provided after the certificate file name, separating it from the file name by a colon.
-  --key määrab võtmefaili asukoha. Kui sertifikaat ja võtmefail on üheks liidetud, siis seda ei ole vaja määrata.
+  --key determines the location of the key file. It is not necessary, if the certificate and key files are merged into a single file.
- Seetõttu määrataksegi võtme parool --cert juures, mitte siin.
+This is why the key password is specified with the --cert option, not here.
-== SOAP päringu tulemused ==
+== SOAP request results ==
-=== Õnnestunud päring ===
+=== Successful request ===
-Õnnestunud tulemus (lisatud reavahetused loetavuse parandamiseks):
+Successful request (line spacing added for easier reading):
 <pre>
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 145: / Line 144: @@
 </pre>
-=== Vigased päringud ===
+=== Invalid requests ===
-Viga GET parameetris (KiCompany asemel KiCompan):
+Error in GET parameter (KiCompan instead of KiCompany):
   curl -d @data.txt -u 1234:abc123 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompan</nowiki>
 <pre>
@@ Line 167: / Line 166: @@
-Vigane kasutaja või parool või sertifikaat:
+Invalid user name, password or certificate:
   curl -d @data.txt -u 1234:abZZ23 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
 <pre>
-Krediidiinfo veebiteenuse kasutaja autentimine ebaõnnestus! Abi saamiseks võtke ühendust Krediidiinfoga telefonil (+372) 6659600.
+Authentication of Krediidiinfo web service user failed! For assistance, please contact Krediidiinfo by calling (+372) 6659600.
 </pre>
-Kasutajal ei ole õigust [[KiCompany]] kasutamiseks, pöörduge kliendihalduse poole:
+User has no permission to use [[KiCompany_en | KiCompany]] please contact our customer service:
   curl -d @data.txt -u 1234:abc123 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
 <pre>
@@ Line 193: / Line 192: @@
-SOAP päring puudub:
+Missing SOAP request:
   curl -u 1234:abc123 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
 <pre>
 </pre>
-(tulemust pole)
+(no results)
-SOAP päringus endas on viga:
+Error in the SOAP request itself:
   curl -d @vigane.txt -u 1234:abc123 <nowiki>https://services.krediidiinfo.ee/soap.php?name=KiCompany</nowiki>
 <pre>
@@ Line 214: / Line 213: @@
 </SOAP-ENV:Envelope>
 </pre>
-või
+or
 <pre>
 <?xml version="1.0" encoding="UTF-8"?>

SOAP service testing: Difference between revisions

Revision as of 13:11, 15 June 2012

Contents

Network test

SOAP request example

Using curl

curl SOAP request, using HTTP Basic Authentication

curl SOAP request, using a certificate and a key as the authentication method

SOAP request results

Successful request

Invalid requests

Navigation menu

SOAP service testing: Difference between revisions

Revision as of 13:11, 15 June 2012

Network test

SOAP request example

Using curl

curl SOAP request, using HTTP Basic Authentication

curl SOAP request, using a certificate and a key as the authentication method

SOAP request results

Successful request

Invalid requests

Navigation menu

Search