Re: [Tiki-devel] Tiki API discussion

I've confirmed a time for the combined session for
https://tiki.org/Tiki-API-Knowledge-Sharing-2021 : 1800 UTC 25-Nov-2021
https://www.timeanddate.com/worldclock/fixedtime.html?iso=20211125T18&ah=2
on https://tiki.org/live Victor, I and anyone else interested and able to
can stay for more technical discussion after.

Jonny, we'll try and cover what we can during the combined session before
you have to head out. We'll see how it goes and can always follow up later
if needed.

On Mon, Nov 22, 2021 at 2:02 PM Jonny Bradley via TikiWiki-devel <
[email protected]> wrote:

> Sorry Nelson, very little spare time or energy this week, maybe next?
>
> Can't do (difficult things in the) evenings just now I'm afraid...
>
> jb
>
>
>
> > On 22 Nov 2021, at 15:32, Nelson Ko <[email protected]>
> wrote:
> >
> > Thanks Victor and Jonny - I added a new slot for Thurs Nov 25 right
> after the 1st one because I am thinking of having the combined and
> technical session back-to-back. Wondering if you can make that one (you can
> indicate on there).
> >
> > On Mon, Nov 22, 2021 at 4:00 AM Victor Emanouilov <[email protected]>
> wrote:
> >> It will be great to meet! I filled in my slots in the Convene plugin...
> >>
> >> Regards,
> >> Victor
> >>
> >> On 11/18/21 7:24 PM, Nelson Ko wrote:
> >>> All good points. Generally speaking, I tend to agree with Ricardo too.
> >>>
> >>> About 2 months ago, we (i.e. the company I'm with) also started
> developing a REST API for our SaaS platform which uses Tiki. Right now, we
> are developing a mobile app which uses this API via OAuth2 login. I'd like
> to share our experience so far, and also the generic parts of our code so
> that it can be helpful to the people who are developing the Tiki API. So I
> have decided to organize 2 webinar sessions to walk through what we have
> done and the lessons learned so far. As it sounds like Victor is anxious to
> get moving with more development, I've provided time options for next week.
> Please indicate your availability at
> https://tiki.org/Tiki-Api-Knowledge-Sharing-2021 using the Convene
> plugins.
> >>>
> >>> Nelson
> >>>
> >>>
> >>>
> >>> On Thu, Nov 18, 2021 at 4:07 AM Victor Emanouilov via TikiWiki-devel <
> [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]> 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
> >>>>
> >>>> 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, e.g.
> >>>> 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.
>
> >>>> 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]
> >>>> https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel
> >>> _______________________________________________
> >>> TikiWiki-devel mailing list
> >>> [email protected]
> >>> https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel
> >
>
>
> _______________________________________________
> TikiWiki-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel
>

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