Re: [Tiki-devel] Tiki API discussion
Victor Emanouilov via TikiWiki-devel <[email protected]>
| Newsgroups | gmane.comp.cms.tiki.devel |
|---|---|
| Message-ID | <[email protected]> |
We will extend Tiki oAuth support for the API! Nelson, thanks for the knowledge sharing. I will try to come up with a more REST-ful interface for the API in the coming weeks and push updates to the MR in gitlab. There are more and more projects trying to use Tiki as both publisher of data and also subscriber for remote data, so flexibility will be needed here - especially around trackers. Thanks all and looking forward to building something useful here! Regards, Victor On 11/26/21 3:24 AM, Fabio Montefuscolo wrote: > Thank you! > > I watched the video now. That seems to be very nice. > > Well, the OauthServer thing we have right now is very basic. It just > works to establish a session between ConverseJS and OpenFire. Both > Openfire and Tiki share a secret key that validates the oauth token > ConverseJS gets from Tiki and use into Openfire. > > > > > > On Thu, Nov 25, 2021 at 1:52 PM Bernard Sfez via TikiWiki-devel > <[email protected] > <mailto:[email protected]>> wrote: > > Yes we are ;-) > > B > >> On 25 Nov 2021, at 18:39, Fabio Montefuscolo >> <[email protected] >> <mailto:[email protected]>> wrote: >> >> Please, if possible, can someone record the session? >> >> On Wed, Nov 24, 2021 at 2:41 AM Victor Emanouilov via >> TikiWiki-devel <[email protected] >> <mailto:[email protected]>> wrote: >> >> There is. Check https://doc.tiki.org/Tracker-Synchronization >> <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] >> <mailto:christoph.volkert-pJ4oRsUJzJFWk0Htik3J/[email protected]> >> > >> > Geschäftsführer: Michael Bleier >> > Registergericht Mannheim, HRB 700 480 >> > >> > >> > ________________________________________ >> > From: Victor Emanouilov via TikiWiki-devel >> [[email protected] >> <mailto:[email protected]>] >> > Sent: 23 November 2021 15:36 >> > To: [email protected] >> <mailto:[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/ >> <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] >> <mailto:[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] >> <mailto:[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/ >> <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 >> <https://doc.tiki.org/API-Tracker> and >> https://doc.tiki.org/api <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 <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 >> <https://dev.tiki.org/Application-Programming-Interface> >> >>> >> >>> >> >>> >> >>> >> >>> >> >>>> On 18 Nov 2021, at 08:47, Victor Emanouilov via >> TikiWiki-devel <[email protected] >> <mailto:[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] >> <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¶m2=val2 >> <http://tiki.org/api/controller/action?param1=val1¶m2=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] >> <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] >> <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] >> <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] >> <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] >> <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] >> <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] >> <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] >> <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] > <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 _______________________________________________ TikiWiki-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/tikiwiki-devel