[dev] RFC: HTTP API approach (REST)

[Ralf Lang]

Hi,

I have implemented a mock for a resource-centric Horde API (Kind of REST
Level 1).

Major roadblock was understanding how the Horde Controller Framework
(rampage) actually works and where to change bits which seemed to get in
my way. Please comment if this goes into the desired direction. The
earlier I know which bits are not likely to go into upstream horde, the
easier I can adopt.


Overview:

I basically cloned the endpoint file rampage.php into an own app,
changing some details.

We do not auth upfront. We may want to allow public  access to some
resources or use a non-standard userbase, think API users/machine users
or we want to enforce auth per request, i.e. no cookie/session key.
Depends on case

We use a modified RequestMapper to understand registry API names
This RequestMapper looks in the first /slug/ of the URL for API names
(while the original mapper looked for Application names)

Thus, the URL does not reveal which horde app is actually implementing
the resource. The implementing app's routes.php config file matches the
route to a controller and may require an explicit authentication
scenario (like method http-auth, backend horde-auth). Otherwise we fall
back to some configured global (no auth or http-basic)

The original Horde Controller Framework's runner understands pre and
post filters but the default SettingsExporter noops. A base "api"
controller class exists chiefly to override the SettingsExporter for all
derived controllers.

This SettingsExporter understands authentication and permission related
optional extra keys in routes.php and configures suitable pre filters.

I intentionally did not yet try to integrate this with either
base/rampage.php or base/rpc.php at this point.


Status:

The current repo ships with a toy usecase where the "api" app itself
exposes an endpoint /api/introspection/apps
However, the auth module is not yet implemented, the endpoint currently
runs unauthenticated.
The controller is just for presentation. A real base controller will
need to provide different behavior on GET, POST and most likely some
request details/headers (json or xml, language preference, pagination...)

https://github.com/ralflang/horde-api

This is really just a first draft to see if it's worth to continue or if
it is a flawed design. There is so much to add next.


How to run:

- checkout into a horde git tree as "api" directory
- copy the registry snippet from /doc/ to base/config/registry.d/
- run git-tools dev install
- create a config via the menu
- you can run or ignore the db migration file, doesn't matter
- hit $horde/api/introspection/apps for the toy usecase

Regards,
Ralf

-------------- next part --------------
A non-text attachment was scrubbed...
Name: pEpkey.asc
Type: application/pgp-keys
Size: 1757 bytes
Desc: not available
URL: <https://lists.horde.org/archives/dev/attachments/20190104/a6285bae/attachment.bin>