Application internal API

Question

I am currently building a small python CLI (Command Line Interface) application with ambition. In the first development phase I would concentrate on making it work through the CLI interface only, but in the second phase I will make it work through a GUI.

To avoid a lot of refactoring of the functionnalities and to keep both version running on a similar code base I was thinking of developping my own internal API to handle processing.

IE:

• Loading the config file
• Saving the config file
• Logging info (through CLI or log files)
• And the general process of the application

I was wondering where to start and what to keep in mind while building an internal API?

I already watched the following presentation : How To Design A Good API and Why it Matters or and read the text version

** What I mean by API is : If i want to load the configs I would only have to do something like config = api.load.config(path/to/config/file) and i would get a dictionnary (or object, yet to be determined) without having to detect the type of file and if the file exists, that part would be handled by the internal API's framework

Answer 1

Since config file reading and writing is already part of Python, as are log files, you don't need to do any API design.

Just read and use. It's already been done for you.

http://docs.python.org/library/configparser.html

http://docs.python.org/library/logging.html

For the rest of your application, don't think too deeply about it. Indeed, the less thinking the better.

Your application (either CLI or GUI) allows an actor to interact with objects of certain classes. Those core classes define your model. It's the same in all presentations (CLI, GUI, WEB).

First, design the model classes. Those classes should be in a tidy package (or better, a single module) and should work from scripts and unit tests.

Second, design the CLI that uses those underlying classes.

The underlying classes are -- essentially -- an API. But don't read a lot of stuff about API design. Just design the underlying classes well.

Third, design the GUI that uses the underlying classes. While doing this, you'll have the urge to refactor your CLI and model design to make everything simpler and more convenient. This is good.

But don't read a lot of stuff about API design. Just refactor the classes well.

The secret is this.

Unit Test

Once you have good unit tests for your model, you can refactor the CLI and GUI and be confident that everything works. Don't be afraid to refactor. It's easier to build something that works and refactor it than it is to read a book about API design, design the API, and then learn a bunch of hard lessons about your real-world application being a little different from the text-book ideal applications.