Sorry. I promise to code my tutorials better

Don’t you hate when someone writes a tutorial showing you how to do something — in a way no one in the real world would ever do?

• No error handling
• Just Hello World and nothing more
• Using brute force
• Half-completed tasks
• Simple and obvious features (that everyone would use) not used

Well, while testing my tutorial to see if it works on the new Free-Tier services (see this blog by Riley Rainey), I suddenly realized how much better I could have written the tutorial. And I noticed it because the API I was calling failed, and therefore my entire webhook failed. 🤦‍♂️

Webhook for SAP Conversational AI

I had written a tutorial to show how to write a Python webhook that could be called from SAP Conversational AI. It’s probably the tutorial I’m most proud of, since I had to learn SAP Conversational AI, then Python, then Flask, then BTP, then CF, then CF CLI, then a few more things.

But during testing to see if it works on BTP Free-Tier, I saw a few things I should have done better.

• The first thing I noticed was that I had to enable CF for the whole thing to work. Not terrible, most people would figure it out, but still.

• During the CF CLI process, I told people to select their subaccount. But on the system I was now using, I had only one subaccount, so it was automatically chosen for me.
• Still during the CF CLI upload process, I got an error because I had enabled CF but did not create a space.
• And finally during the CF CLI upload process, I got an error because the version of Python I had specified for the app was from a “long time ago” – 3.8.5. Why I did not long ago specify 3.x, I don’t know.

• Now for the webhook code. The API service I was calling failed, which crashed my webhook. so the first thing I did was to redo my code. It had been like the following – no error handling, no worries if the API was down:

  url = "https://cat-fact.herokuapp.com/facts/random?animal_type=" + animal + "&amount=1"
  
  r = requests.get(url)
  fact_data = json.loads(r.content)
  
  

  Now I changed the code to still work if things went bad:

  url = "https://cat-fact.herokuapp.com/facts/random?animal_type=" + animal + "&amount=1"
  nodata = {"text" : "No data"}
    
  try:
      r = requests.get(url, timeout=5)
      fact_data = json.loads(r.content)
  except:
      fact_data = nodata
  

  • I added the nodata variable to hold dummy text so I could return something no matter what, and so my webhook would continue to work.
  • I put the web call in try/except block, to capture when the call failed (like now).
  • I put a timeout for the web call because, even though I now caught the error, my webhook was hanging and taking a long time to return.
  • I added code to set my data to the nodata variable, in the case of an exception.

They say you learn the most when you struggle, make mistakes, tinker. I felt powerful, finding a better way to code, not just the fastest way. These were small victories, but I felt I was gaining some real understanding.

Of course, I’m sure you can find other things to improve the tutorial. If you do, feel free to open a GitHub issue or comment on this blog.

Better Tutorials

I will redouble my efforts to have tutorials reflect more real-world situations, without making it so complicated that you can’t learn the basics of what you came to learn in the first place.

See all our fabulous tutorials in the SAP Tutorial Navigator.