Re: [Tiki-devel] Tiki API discussion

Yes, console commands is something to keep in mind as more and more 
functionality is available as a scheduled/background executed job 
through that.

Thanks,
Victor

On 11/19/21 12:49 AM, Ricardo Melo wrote:
> Hi Victor,
>
> it makes sense, if we go into a RESTful api we can probably leverage - 
> where possible - what is built for AJAX as it is close in some of the 
> cases. Fully agree that we should be reusing the same "business logic" 
> but as you know, more often than not, we have plenty of business logic 
> on the entry points (controllers for Ajax, entry point files for the 
> rest)  that makes it hard to reuse, maybe is an opportunity to move 
> that away from controllers so it can be reused in the different entry 
> points (console commands included)
>
> Ricardo
>
> On Thu, Nov 18, 2021 at 9:06 AM Victor Emanouilov <[email protected] 
> <mailto:[email protected]>> wrote:
>
>     Hi Ricardo,
>
>     Your input is quite valuable, thanks. I was thinking in the same
>     direction but felt somewhat sorry to skip so much code formatted
>     as services currently. It is really a tradeoff and hard decision
>     to make. What do you think of the idea of an adaptor that is
>     exposing the endpoints in a RESTful manner? We can follow your
>     suggestion here to make it progressive, start with the most common
>     CRUDs for wiki pages, trackers, files, etc. and also refactor
>     services where necessary to support both internal ajax services
>     and external API requests. In my mind, changing a tracker item,
>     for example, should always go through the same steps no matter who
>     does it and what interface do they use. Different interfaces
>     should only format the input and output accordingly but then
>     everything else concerning permissions, field validation, data
>     format and storage, etc. should be unified. That's why I am so
>     inclined on reusing the existing services and modifying them when
>     necessary.
>
>     I agree that if we want to support GraphQL interface, we will have
>     to do it standalone as our existing libs just don't fit in the
>     idea of connected nodes - each lib deals with one (or a couple) of
>     db tables and data retrieval is sequential.
>
>     Regards,
>     Victor
>
>     On 11/18/21 10:10 AM, Ricardo Melo wrote:
>>     Hi Victor,
>>
>>     Thank you for detailing all the options.
>>
>>     From my perspective, AJAX services would not be good enough.
>>     Today some are returning HTML, others JSON, etc. I think if we go
>>     in that direction we will end up with a broken and
>>     inconsistent API - while still needing to add more services (that
>>     then won't really be AJAX). Playing our cart well here could also
>>     mean in the long run we could migrate some of AJAX services to
>>     use the new (and consistent) API deprecating some of the existing
>>     services.
>>
>>     From top of mind, 90%+ of the benefit will be from creating 2 or
>>     3 API's: CRUD for Wiki pages, CRUD for Trackers, CRUD for file
>>     gallery and while that is a lot of work, I think can be done
>>     progressively and leveraging internal classes / resources, while
>>     keeping a slim shim that would make the API consistent.
>>
>>     On the specific format for the API, I see a lot of advantages to
>>     having a GraphQL interface that solves the N+1 query problem to
>>     the API, but I acknowledge that the REST interface would be
>>     faster to implement and would be easy for other developers to
>>     contribute (likely).
>>
>>     Going with one format or the other, we will need to add a shim
>>     layer for the API, so we can probably leverage Annotation to have
>>     the documentation done on object properties.
>>
>>     But again, just my 2cts.
>>
>>     Ricardo
>>
>>     On Wed, Nov 17, 2021 at 12:35 PM Victor Emanouilov via
>>     TikiWiki-devel <[email protected]
>>     <mailto:[email protected]>> wrote:
>>
>>         Dear dev community,
>>
>>         We are adding an API to Tiki 24. Your input will be highly
>>         valuable.
>>
>>         As discussed previously with Jonny, Marc and others, first
>>         step was
>>         exploring the opportunity of exposing our ajax-related
>>         services as an
>>         API. This makes sense but also has some drawbacks discussed
>>         below. Main
>>         benefits:
>>         - extremely quick start - we have many services accessible
>>         via ajax for
>>         internal Tiki operations that can be exposed as an API for
>>         external
>>         systems to retrieve data and manipulate data
>>         - having one and the same code used by internal components
>>         and external
>>         services will ensure interoperability in the future and same
>>         behavior
>>         inside and outside Tiki
>>         - avoid designing and especially coding a whole new level of
>>         services
>>         for the API
>>         - opportunity to enhance existing ajax services with missing
>>         pieces like
>>         permission enforcement and documentation
>>         Main drawbacks:
>>         - lack the possibility of designing an API around an idea
>>         (resources/restful or graphql)
>>         - lack versioning support - changing an ajax service in Tiki
>>         automatically changes the API which possibly breaks existing
>>         integrations (though we can try to be as much
>>         backward-compatible as
>>         possible and also provide a list of breaking changes when
>>         upgrading Tiki)
>>         - existing services are not restful, neither graph-based, so the
>>         resulting API is non-standard
>>         - some of the existing services are not designed to be
>>         exposed via API -
>>         e.g. Cypht ajax controllers
>>
>>         Having these points in mind, I started a MR with the
>>         quick-win method of
>>         exposing Tiki ajax services here:
>>         https://gitlab.com/tikiwiki/tiki/-/merge_requests/1028
>>         <https://gitlab.com/tikiwiki/tiki/-/merge_requests/1028>
>>
>>         Solved some of the problems with authentication (currently
>>         bypassing all
>>         standard Tiki auth methods and allowing bearer token
>>         authentication only
>>         for now), CSRF (turning it off for API but also disabling
>>         session
>>         cookies, so CSRF are not possible via the API), ensure
>>         requests are
>>         stateless and no JS or other funky stuff is going on. Now we
>>         have the
>>         remaining TODO items like documenting the services, enforcing
>>         permissions, consider versioning and restful resources. I
>>         consider 3
>>         possible ways to go forward but needed your input before
>>         investing more
>>         time:
>>
>>         1. Leave the API urls like now 100% based on the ajax
>>         services. Typical
>>         URL is tiki.org/api/controller/action?param1=val1&param2=val2
>>         <http://tiki.org/api/controller/action?param1=val1&param2=val2>,
>>         e.g.
>>         tiki.org/api/tracker/view?id=12
>>         <http://tiki.org/api/tracker/view?id=12>. Enhance services
>>         with permissions
>>         (where missing), document endpoints, input parameters and
>>         output.
>>         Versioning seems impossible in this case. At least the standard
>>         versioning we are used to see. Maybe we can do versioning
>>         based on Tiki
>>         version - API version 24 is one and the same for all Tiki 24
>>         releases,
>>         then we have version 25, etc...
>>
>>         2. Add an adapter between ajax services and API. Make adapter
>>         versionable (so we have API versions - any time an ajax
>>         service is
>>         changed, we keep old behavior and add a new adapter for the new
>>         version). Adapter will also help us come up with more
>>         standard restful
>>         API endpoints and input/output. It can skip certain ajax
>>         services that
>>         doesn't make sense to be exposed. Permissions should still be
>>         in the
>>         services themselves as currently, it is possible to get any
>>         object
>>         attribute without even logging in Tiki with a URL like this
>>         https://tiki.org/tiki-ajax_services.php?controller=attribute&action=get&type=trackeritem&object=2856&attribute=tiki.geo.lat
>>         <https://tiki.org/tiki-ajax_services.php?controller=attribute&action=get&type=trackeritem&object=2856&attribute=tiki.geo.lat>.
>>
>>         Documentation will be based on the newly written adapter
>>         rather than
>>         existing ajax services. Will take more time but solve most of
>>         the
>>         drawbacks. This is my preferred option.
>>
>>         3. Design, write and document an API from scratch. We can
>>         make use of
>>         existing ajax services in terms of code but don't depend on
>>         their
>>         controller/action architecture - here we have the utmost
>>         flexibility to
>>         design a graphql or restful API but also the most
>>         time-consuming.
>>         Without a specific use-case, a project or a subset of
>>         Tiki-stored data
>>         and functionality to expose, I think it will be a waste of
>>         time for now.
>>         Also, one more bit here that's pretty important is the fact
>>         that Tiki as
>>         a web application is stateful in so many ways - it has
>>         extensive use of
>>         the PHP session that is not available in an API. Adding a proper
>>         stateless API requires refactoring all those interal code
>>         elements to
>>         depend on incoming params or database rather than the session
>>         which is a
>>         daunting task to even think about. Tiki will certainly
>>         benefit from this
>>         refactor but at a price of a huge time commitment.
>>
>>         I also have a question about API documentation. We have a
>>         bunch of
>>         options here with most prominent ones being Swagger
>>         (OpenAPI), Raml and
>>         API blueprint - all of which require a separate set of
>>         documentation
>>         sources (in yaml, json or markdown format). We will need to
>>         go through
>>         existing services and document endpoints, required params,
>>         input,
>>         output, etc. Definitely a big task to do. I think there is
>>         also an
>>         option to use inline documentation - PHP class and method
>>         annotation
>>         documentation that can be exported to a visually appealing
>>         html doc. Not
>>         as robust as the first set of tools I mentioned but having
>>         the docs and
>>         the code in one place has its benefits (easier updates for
>>         example).
>>         Anyone has any preferences here?
>>
>>         Thanks!
>>         Victor
>>
>>
>>
>>         _______________________________________________
>>         TikiWiki-devel mailing list
>>         [email protected]
>>         <mailto:[email protected]>
>>         https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel
>>         <https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel>
>>

_______________________________________________
TikiWiki-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel