Safaricom Integration Nightmare part 2

This is a sequel to https://medium.com/@kmarima/safaricom-integration-nightmare-e99a1f6bf893#.m8y12mvgn .

I have some good news and unfortunately more bad news. My integration is not yet complete. This is partly my fault because i had to dedicate time to more predictable projects .. gotta pay the bills. Now to the good news … the VPN setup is complete .. …. *ululations* though i had to get someone to do it for me.

So what am i complaining about this time ? .. I’m dedicating this post to the very confusing and perplexing Safaricom API Documentation and Architechture. I may have mentioned part of this in my previous blog , but I’ve had more time to look at it and i think i have a little more venting to do .. bear with me.

When I complain to Safaricom (which i do … a lot) , the response i always get is “why not get someone who has done it before to help you” . 
Yes, I know , others have walked down this path before me …. successfully … without writing two posts (at the moment) about it … What makes me think i’m special ? .. First of all , I must salute those who completed this task successfully , they are definitely much better developers than i am. Some have even open sourced their work to ease the pain for the rest of us.
Shout out to Eugene Mutai for Project Mulla and to Komu Wairagu for his sample code. However Safaricom …. Just because others had to fetch water from the well , doesn’t mean that we shouldn’t get pumps right ? 
Especially if the pumps are within reach and in this case …. they very much are!!

Ok, now net’s break it down to specific issues 
1. API Documentation in a ZIP file
Ok , so to get the api documentation you have to go here and download a zip file … Before we even unpack the contents of the zip file , lets discuss why this is a bad idea.
Once i download the zip file , i have it offline (mind blowing right ?) meaning that in case Safaricom makes updates to the documentation , i would have no way of knowing that, since they don’t even get my email at this point. 
The very simple solution to this is to have it online. there are simple tools for that … actually someone even did an unofficial API Documentation for you.

2. SOAP
Dammit Safaricom just use REST . I mean seriously why do i to craft such voodoo so that i can send 6 parameters… Just Agrrrrr

$xml_string = ‘<soapenv:Envelope
xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/"
xmlns:req=”http://api-v1.gen.mm.vodafone.com/mminterface/request">
<soapenv:Header>
<tns:RequestSOAPHeader
xmlns:tns=”http://www.huawei.com/schema/osg/common/v2_1">
<tns:spId>’.$spId.’</tns:spId>
<tns:spPassword>’.$encpass.’</tns:spPassword>
<tns:timeStamp>’.$time.’</tns:timeStamp>
<tns:serviceId>’.$serviceId.’</tns:serviceId>
</tns:RequestSOAPHeader>
</soapenv:Header>
<soapenv:Body>
<req:RequestMsg>
<![CDATA[
<?xml version=”1.0" encoding=”UTF-8"?>
<request
xmlns=”http://api-v1.gen.mm.vodafone.com/mminterface/request">
<Transaction>
<CommandID>PromotionPayment</CommandID>

3. Client Libraries & Tutorials
Ok … So since you guys are hell-bent on using SOAP .. how about you build some client libraries- at least for the more popular programming languages. Or maybe some tutorials for us less skilled developers to follow ? please ? Like seriously … what the hell is this (image below)? Check out what Lipisha is doing with REST and check out their client libraries on their Github …

When documentation is clear … you really don’t have to resort to weird looking diagrams to explain your architecture. Just from one glance at the Lipisha documentation … i know exactly what parameters i need to pass … and how to get feedback …. All without having to scroll up some ugly word document to remind myself what SAG stands for. Which brings me to my next point.

4. The Documentation
Not sure if i can even call it documentation … that would be an insult to documentations worldwide.

Overview of the B2C Documentation

Isn’t that a sight to behold. 
As a developer, all I’m looking for when I’m looking at the documentation is 
1. What parameters should i pass?
2. Where am I sending the request ?
3. What response should i expect once I send a request?
But noooo … Safaricom decides i have to read 51 pages of documentation to figure that out . I am yet to understand where this(below) applies

The whole point of having an API & API Documentation is to make it easy for developers to integrate. This one here only confuses me further. And I’m sure all this information in the documentation is important, but how you organize it makes it easy to understand.

5. Eat your own dog food

Eating your own dog food, also called dogfooding, is a slang term used to reference a scenario in which a company uses its own product to test and promote the product.
 Dogfooding can be a way for a company to demonstrate confidence in its own products, and a way to test it in real-world usage. Hence dogfooding can act as both quality control and a kind of testimonial advertising

Here’s a suggestion … hire an average developer, let him/her go through this integration process from start to finish without assistance. Then call me so that i can tell you “I TOLD YOU SO” because that developer will have the same issues that I’ve been lamenting about.

6. Developer Sandbox

Fundamentally, an API sandbox is an environment that testers can use to mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on. — https://smartbear.com/learn/api-testing/what-is-an-api-sandbox/

The process of B2C API intergration right now as i understand it is this.
1. Do the VPN connection
2. Test on http
3. Test on https
4. Deploy 
I’m not even really sure about the process because it is not clearly covered in the documentation … and the documentation is horrible … I digress.
Anywho .. since safaricom offers no sandbox the you have to first go through the process of Setting up a VPN … Chatting with a guy called Steve to help you set up more stuff, sacrificing your pet chihuahua etc before you can even test your code …A sandbox will pretty much eliminate having to chat with Steve (I’m sure he would like that) and step 2&3 … coz it will allow the developer to do tests without being under the watch of Safaricom’s financial services team … this will hopefully give them time to write better documentation :) . RIP Chihuahua.

There’s probably a lot more I can complain about … Hopefully there won’t be a third post … Bob Collymore if you happen to see this , do something about it.

Again my email is me@kmarima.com , feel free to email me with insights. I clearly have a lot to learn.

Like what you read? Give Kariuki Marima a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.