Re: [Tiki-devel] Tiki API discussion

Please, if possible, can someone record the session?

On Wed, Nov 24, 2021 at 2:41 AM Victor Emanouilov via TikiWiki-devel <
[email protected]> wrote:

> There is. Check https://doc.tiki.org/Tracker-Synchronization - you can
> simulate the sending party via curl or another http lib and actually
> create tracker items remotely. Please send me a private email if you
> want some examples, so we don't spam the list...
>
> Regards,
> Victor
>
> On 11/23/21 4:39 PM, Christoph Volkert wrote:
> > I would like to do that. But found no way to do it, no documentation and
> i was told that what i wanted (creating tracker items) is not possible at
> all from remote.
> >
> >
> > Mit freundlichen Grüßen
> >
> > Christoph Volkert
> >
> > Senior IT-Administrator
> >
> > ITeanova Consult GmbH
> > Eppelheimer Straße 13
> > 69115 Heidelberg
> >
> > Tel.:   (+49) 6221 77875-41
> > E-mail: christoph.volkert-pJ4oRsUJzJFWk0Htik3J/[email protected]
> >
> > Geschäftsführer: Michael Bleier
> > Registergericht Mannheim, HRB 700 480
> >
> >
> > ________________________________________
> > From: Victor Emanouilov via TikiWiki-devel [
> [email protected]]
> > Sent: 23 November 2021 15:36
> > To: [email protected]
> > Cc: Victor Emanouilov
> > Subject: Re: [Tiki-devel] Tiki API discussion
> >
> > Sure, I wasn't meaning to exclude IT-Administrators, sysadmins, devops,
> > etc. roles from using the API. Thanks for sharing those use-cases, they
> > will definitely be possible via an API. However, even as of today, they
> > seem to be possible if you configure Tiki source auth (via http auth)
> > and use ajax services to create new tracker items with a simple HTTP
> > post call from your bash scripts (using curl or whatever HTTP lib you
> > have in hand).
> >
> > Regards,
> > Victor
> >
> >
> > On 11/23/21 1:53 PM, Christoph Volkert wrote:
> >>> Tiki administrators and configurators will probably stay away from the
> API as they don't write code.
> >> Sorry, that's not true.
> >> Let me explain it as a IT-Administrator with about 20 years experience.
> >>
> >> Even IT-Admins do not name themselves "coder" and some hate coding, at
> least in more complex hybrid environments most IT-Admins are script-junkies.
> >>
> >> There are a lot of scripts to write. To automate functions and tasks
> and to glue different systems together into one application.
> >>
> >> And that's where the tracker-"API" of TikiWiki should jump in.
> >>
> >> Actually, i migrate from MS Sharepoint to TikiWiki. In Sharepoint,
> there is a list / log (similar to a tracker) of all our different
> system-Backups that are executed regular in our local environment.
> >> Those backups are executed by powershell (WebServiceProxy) and bash
> scripts, but all those backup-script document their successful job into
> that sharepoint list via a "API"-call.
> >>
> >> Another example is the shutdown-script that shuts down, via "API"-call
> (e.g. https://blogs.sap.com/2014/06/12/scripting-sapmmc-operations/),
> our various SAP application servers in case of a power failure. The UPS
> starts a script that executes the SAP netweaver shutdown procedures and
> after that,  shuts down the operation system of that SAP server node. All
> that is done via a "API" call
> >>
> >> Therefore, such a API-call for TikiWiki trackers is not only used by
> developers, but for every day production in a real environment. In my case,
> i really need that function. And because such a API is not only used by
> developers but by admins without deeper programming skills, it should be
> easy to use for the basic functions like displaying and adding tracker
> items.
> >>
> >> Thank you for your efforts
> >>
> >> ________________________________________
> >> From: Bernard Sfez via TikiWiki-devel [
> [email protected]]
> >> Sent: 23 November 2021 10:03
> >> To: Tiki developers
> >> Cc: Bernard Sfez
> >> Subject: Re: [Tiki-devel] Tiki API discussion
> >>
> >> Hello,
> >>
> >> I waited to avoid “one by one thank you” messages and needed some times
> to read and understand.
> >>
> >> Thank you all for making this more understandable (for common mortal)
> and organising this.
> >>
> >> I’ll be following from the back seats. ;-)
> >>
> >> Regards,
> >> Bernard
> >>
> >>> On 20 Nov 2021, at 18:33, Jonny Bradley via TikiWiki-devel <
> [email protected]> wrote:
> >>>
> >>> Hi Bernard
> >>>
> >>> What Tiki has at the moment is a bit like what these guys used in
> Sweden, as you shared the other day (it's a great story!)
> >>>
> >>>
> https://www.wired.com/story/sweden-stockholm-school-app-open-source/
> >>>
> >>> And in Tiki that is what you/we have been partially documenting here
> https://doc.tiki.org/API-Tracker and https://doc.tiki.org/api. The reason
> the city there found it fairly easy to stop the parents using it was that
> it wasn't published and documented.
> >>>
> >>> I think these pages should be updated and renamed maybe, to reflect
> these new plans to make a proper API and make it clear those are notes
> about unofficial ways of accessing AJAX services in older Tikis.
> >>>
> >>> A good example of what a proper one looks like is
> https://stripe.com/docs/api
> >>>
> >>> Hope that helps,
> >>>
> >>> jonny
> >>>
> >>>
> >>> p.s. found this page, we should add these plans to it
> https://dev.tiki.org/Application-Programming-Interface
> >>>
> >>>
> >>>
> >>>
> >>>
> >>>> On 18 Nov 2021, at 08:47, Victor Emanouilov via TikiWiki-devel <
> [email protected]> wrote:
> >>>>
> >>>> Bernard, thanks for the relevant questions! API (short of Application
> Programming Interface) is really meant to be a communication channel
> (interface) between 2 computer systems, so intended API users are
> developers who want to build programs around Tiki - use Tiki data and
> contribute data to Tiki but not using the UI we currently have. Tiki
> administrators and configurators will probably stay away from the API as
> they don't write code. One side-effect of the API will be improving
> inter-Tiki support and ways 2 Tikies share information, but when these
> improvements happen, we will document in a user-friendly way.
> >>>>
> >>>> Regards,
> >>>> Victor
> >>>>
> >>>> On 11/17/21 6:12 PM, Bernard Sfez wrote:
> >>>>> Dear Victor,
> >>>>>
> >>>>> I understand those are developer questions in a developers list.
> >>>>> I also understand that this is an improvement (we are blessed to
> have so talented developers like you are, thanks ;-) ).
> >>>>> I understand also some people knows and discussed this already.
> >>>>>
> >>>>> However I, and may be other Tiki consultants here, have hard time to
> understand what will be the impact for the Tiki configurators and the Tiki
> admins.
> >>>>>
> >>>>> Will it change the existing way to use Tiki and its
> tools/plugins/etc ?
> >>>>> How can we digest and help with documentation ? (Because I guess the
> consultants will be the one to help with the documentation and samples).
> >>>>>
> >>>>> Bernard
> >>>>>
> >>>>> PS: If the next TRM in a few day wasn’t that crowded with topics, I
> would have invite the people who “knows” to explain and demonstrate to the
> people that doesn’t. May be live meeting would help ?
> >>>>>
> >>>>>
> >>>>>
> >>>>>> On 17 Nov 2021, at 14:33, 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
> >>
> >>
> >> _______________________________________________
> >> 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
>

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