#MTN-API
**Code and notes for MTN API **
Us You have seen that this is a fork project i have found that all of resources provided doesn't work only for MTN Zambia but for all MTN Subsidiaries , I don't know for you but for me i didn't even know that a lot of this resources is available(Am based in RWANDA) it's had to intergrate MTN API services with your existing services many developer don't even know at least which step to proceed or even what kind of stack or techs required to be able to intergrate successful with MTN network that why forked this repo and modified it to be in general not only session provided at BongoHive in Zambia great thanks to original Author @Chizzoz ,
So, individuals, entusiasts, etc, interested in utilising MTN services, to see what power can be harnessed from this platform.
##A Web Approach to Integrating MTN API
And below are some highlights:
- Introduction to MTN Developer portal and available resources
- Using SDP32 Interface Simulator. Download it and try it out
- Demo service testing
- The MTN developers portal provides lots of demo projects, free to download and tinker with, in three flavours; C#, JAVA and PHP. Download and test here
- Introducing SOAP and WSDL files
- MTN API makes use of SOAP messages delivered over http. Wondering what a SOAP message is?, READ THIS.
- So, now that you know about SOAP messages, it would be worthwhile to also learn about WSDL files, they also XML formatted files like SOAP messages, but they define the web service to be used, they are sort of the blueprint and validation rule for the SOAP message. Learn about WSDL files.
- Introducing SOAPUI
-
Now, if you downloaded a demo service from the developer portal or used the SDP32 Simulator, you might be wondering why I am introducing WSDL files when you didn't even have to use them. Well, that's where SOAPUI comes in. What is SOAPUI? I picked this right off their website:
SoapUI is the world's most widely-used open source API testing tool for SOAP and REST APIs.
From my experience, I found the SDP32 Simulator rather limited in services and I was not able to get a server-like response after a request from my client app. SOAPUI handles responses and requests beautifully.
- Introducing Developer API Reference Documentation
- To start testing a specific MTN API service, you need to download the relevant WSDL file from the resources page and import it into a new SOAPUI project, then you can use the SOAP messages specified in the API reference documentaion. With your SOAPUI project setup, you can create mock services that will emulate the MTN API server. I found API Reference documents to be extremely helpful in providing message flows and field specifications for messages sent. The API Reference documents include detailed sequence diagrams, sample SOAP messages and SOAP message parameter (field) specifications; like type (string, integer, etc), length, mandatory or not, etc.
- Alternative method to implement demo service using PHP
- I called this a web approach to integrating MTN API, if you are like me, intending to develop something that runs in the browser and not using an IDE like Eclipse EE, working with XML, SOAP, WSDL, etc pose quite a challenge. If you used a PHP demo service, you would have had to include NuSOAP - SOAP Toolkit for PHP and ThinkPHP2.1. Including these other tools, learning how to use them, etc, proved to be too much admin, plus there was the issue of speed. Looked for alternative solutions and finally, thanks to my buddies Google and Stack Overflow, I stumbled upon a number of solutions that I incorporated to come up up with a solution I was pleased with. This involves embedding XML files directly into PHP code and manipulating SOAP responses and requests using a combination of PHP cURL Library, SimpleXMLElement and XPath Path Expressions.
<?php
/*
* Sample Book Store XML manipulation using XPath
*/
$SAMPLE_RESPONSE= <<<XML
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book>
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
<book>
<title lang="en">Bitterness (An African Novel from Zambia)</title>
<author>Malama Katulwende </author>
<year>2005</year>
<price>14.66</price>
</book>
<book>
<title lang="en">Glimmers of Hope : A Memoir of Zambia</title>
<author>Mark Burke</author>
<year>2010</year>
<price>15.98</price>
</book>
<book>
<title lang="en">Salaula: The World of Secondhand Clothing and Zambia</title>
<author>Karen Tranberg Hansen</author>
<year>2000</year>
<price>30.60</price>
</book>
</bookstore>
XML;
$response_xml = new SimpleXMLElement(strstr($SAMPLE_RESPONSE, '<'));
echo '<hr>';
foreach ($response_xml->xpath('//bookstore/book') as $book) {
foreach ($book->children() as $book_details) {
if (!empty($book_details)) {
echo $book_details->getName() . ": " . strval($book_details) . "<br>";
}
}
echo '<hr>';
}
?>Sample code on how to send a SOAP request to specific server URL, receive the SOAP response from server and pull data from response using PHP cURL Library, SimpleXMLElement and XPath Path Expressions
<?php
/*
* Sample code on how to send a SOAP request to specific server URL,
* receive the SOAP response from server
* and pull data from response
* using PHP cURL Library, SimpleXMLElement and XPath Path Expressions.
* Download WSDL file and import in SOAPUI: https://developer.mtn.com/community/portal/site.action?s=devsite&c=detailsResource&lang=en&t=web&resourceId=433&resourceName=%3Cspan%20style=%22color:#1483BB;background:#FFFFFF;">Subscribe</span>_WSDL_6_1&categoryId=&h=resourceSearch&searchName=&search=¤tPage=
*/
// This function will POST the SOAP message to the specified URL
function doXMLCurl($url,$postXML){
$headers = array(
"Content-type: text/xml;charset=\"utf-8\"",
"Accept: text/xml",
"Cache-Control: no-cache",
"Pragma: no-cache",
"SOAPAction: \"run\"",
"Content-length: ".strlen($postXML),
);
$CURL = curl_init();
curl_setopt($CURL, CURLOPT_URL, $url);
curl_setopt($CURL, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($CURL, CURLOPT_POST, 1);
curl_setopt($CURL, CURLOPT_POSTFIELDS, $postXML);
curl_setopt($CURL, CURLOPT_HEADER, false);
curl_setopt($CURL, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($CURL, CURLOPT_HTTPHEADER, $headers);
curl_setopt($CURL, CURLOPT_RETURNTRANSFER, true);
$xmlResponse = curl_exec($CURL);
return $xmlResponse;
}
// This is the SOAP message to be sent to the API, you can replace the SOAP message below with any other SOAP message you wish to test
$REQUEST_BODY= <<<XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/subscribe/manage/v1_0/local">
<soapenv:Header/>
<soapenv:Body>
<loc:subscribeProductRequest>
<loc:subscribeProductReq>
<userID>
<ID>35000001</ID>
<type>0</type>
</userID>
<subInfo>
<productID>12345678</productID>
<!--Optional:-->
<operCode>1</operCode>
<!--Optional:-->
<isAutoExtend>1</isAutoExtend>
<channelID>1</channelID>
<!--Optional:-->
<extensionInfo>
<!--Zero or more repetitions:-->
<namedParameters>
<key>?</key>
<value>?</value>
</namedParameters>
</extensionInfo>
</subInfo>
</loc:subscribeProductReq>
</loc:subscribeProductRequest>
</soapenv:Body>
</soapenv:Envelope>
XML;
// Catch any error in getting response from server and return error SOAP message
try {
$full_response = doXMLCurl('http://localhost:9080/SubscribeManageService/services/SubscribeManage', $REQUEST_BODY);
} catch (\Exception $e) {
$ERROR_RESPONSE= <<<XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<soapenv:Fault>
<faultcode>Server</faultcode>
<faultstring>Missing operation for soapAction [] and body element [null] with SOAP Version [SOAP 1.1]</faultstring>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>
XML;
return $ERROR_RESPONSE;
}
// Get server response and manipulate using XPath
$response_xml = new SimpleXMLElement(strstr($full_response, '<'));
echo '<hr>';
foreach ($response_xml->xpath('//*[name()=\'loc:subscribeProductRsp\']/*') as $body) {
$ns = $body->getName();
echo $ns . ": " . strval($body) . "<br>";
}
echo '<hr>';
?>
- Creating API
- Lastly, you might want to extend your app beyond the browser to other mobile platforms, SMS, USSD, etc using URL queries. To do that, you will also need to create your own API that provides interaction with your app.
So, that's about it. Thank you for your time!