REST APIs. They’re all over the web. You could directly code against them in Python, but after a while, you start repeating yourself and your code becomes crufty and difficult to maintain. Your “high-level” business logic becomes intertwined with the “low-level” nitty-gritty logic of parsing I/O. And that’s bad news.
The smart solution is to abstract away the REST API with a “wrapper” library module more commonly known as a Software Developer Kit (SDK). Take all that nitty-gritty detail and push it down to where you don’t need to worry about it anymore and then just import your Python module and code directly against it.
If you’re using an intelligent IDE like PyCharm or VS Code, then you can leverage Type Hinting for auto-code completion. Keep your business logic separate from the boring details and your code is faster to develop and easier to maintain. Here’s how to do it:
Step 1: Read the Docs and use PostMan to understand the REST API
Step 2: Create a low-level REST adapter
Step 4: Implement Exception handling and raise new custom Exceptions
Step 5: Create a new Response/Result model
Step 8: Create strong data models
Step 9: More complex data models
Step 10: Implement Inheritance with data models
Step 11: Create high level endpoint abstractions
Step 12: Create more endpoints and helper methods
Step 14: Write your unit tests
Step 15: Make an app that consumes your module
4 replies on “Python JSON REST API wrapper library: a How-To in 15 simple steps”
[…] This is the 1st chapter in a multi-part series called “How to write a Python3 SDK library module for a JSON REST API in 15 simple steps“ […]
Very nice article series! This covers a lot of topics I’ve had to learn the hard way by building my own REST API client. Here are a couple other points worth mentioning:
* For more complex data models, the attrs library (https://github.com/python-attrs/attrs) is fantastic! It has handy features for validation, conversion, and lots more. It also has some nice integrations with other popular python tools and libraries like mypy and rich.
* A caching layer is extremely useful for an API client, especially if the server provides caching headers, or if it’s slow or rate-limited. I currently maintain requests-cache (https://github.com/reclosedev/requests-cache), which is built for exactly this kind of use case.
Thank you! This helped advance our development a lot with high quality code!
Hi,
I just wanted to express my gratitude to you for putting together this fantastic and comprehensive guide! I am quite new to Python and my programming experience resides purely in using MATLAB for my mechanical engineering day job. I’m trying to develop a piece of software that uses multiple API’s to get data for retro games and had no idea how to create a robust and efficient wrapper. This guide has made it a piece of cake and it has really helped me learn how to structure my code, use object oriented programming, and write DRY code. This guide is written in a way that makes it easy to digest and understand, with each step of the process being explained in full and no details left out.
At the time of writing this comment, I haven’t committed my changes to GitHub yet, but when I do I will be sure to reference your work
Kind regards,
Jamie