REST API - New feature

[mtchetch]

The API question is surfacing again, and I will reboot this conversation, which still has an unfinished pull request hanging from 2018.

@emaijala We have a use case for a REST API as part of a customer project that currently uses an old version of MLinvoice with custom changes to the codebase. We are planning to implement a REST API as a separate pull request or as a series of pull requests. The aim is to provide an upgrade path and a stable way of integrating MLInvoice with other systems that need invoice generation, Finvoice XML generation, etc.

Please share your thoughts on what should be considered and how the API should be implemented so that it can be accepted into the codebase.

[emaijala]

@mtchetch Here's what I've thought could be workable, or at least the route I've been planning to take:

• Introduce something like the Slim framework to give the application some structure so that not everything is a hack. This would add proper routing and request handling with PSR-7 support (for which Guzzle's would be a natural choice because Guzzle is already used in MLInvoice). Adding Slim would not require everything to the ported over right away, though that should be the long-term goal.
• Also add e.g. PHP-DI for dependency injection.
• Design the API as an OpenAPI spec (e.g. using Swagger Editor).
  • Allow one to POST new records, PUT updated records and also use PATCH to just update some fields.
• Add routes based on the OpenAPI spec, and action classes to handle them.
• Add Doctrine ORM for database access. This has been something I've wanted to do for a while, because it would add nice object-oriented way to handle records and their relations, and save a lot of manual work.
• Add support for defining API keys with customizable permissions (or at least design it to support adding permissions later).

Okay, this seems like a long list, but the idea here is not to just add another php file that does things in a custom way but to use existing tools. If this all seems to be too much, maybe splitting the work would be possible too. And nothing above is chiseled in stone. The framework could be something else as well. I chose Slim here because it's lightweight and doesn't require a lot of plumbing.

Anything that does REST compatible routing will necessary add some requirements for the web server too. It needs to be able to pass requests to the entrypoint script regardless of the path in the request. So far MLInvoice has not required this but has been able to run after being dropped somewhere where index.php and other entry point scripts can be accessed via the web server, which has been handy with simple web hotels. In practice the routing will require mod_rewrite or mod_dir (FallbackResource) tp be available and configurable.

One possibility is that I create a skeleton for adding the actual functionality. Or add basic invoice manipulation as an example and let you add what you need in addition.

One big question is how authentication should be handled. Apache tends to swallow the Authorization header a client sends, and passing it on is another thing that needs additional Apache configuration. An API key could of course be passed in a custom header, but not all clients support that. I think that using OAuth 2.0 would make sense, but it would also add a bit more complexity (on both sides).

[emaijala]

I'm going to take a stab at doing some of the groundwork.

[emaijala]

It's nowhere near functional yet, but in case anyone is interested in following the progress, dev-slim-doctrine is the development branch for the huge refactoring.