Re: [Tiki-devel] Tiki API discussion

Brendan, thanks for the answers. I will just complement them here so 
hopefully Torsten can see the bigger picture - we need an API in Tiki to 
solve two basic problems

- let external systems or developers write code (modules/plugins, etc.) 
around data stored in Tiki - let them access and manipulate that data in 
a straightforward way

- let 2 Tikies communicate in a more standard way. Currently we have 
some pieces like remote tracker synchronization, auth sources, 
webservices plugin but none of these actually allows us to solve a use 
cases like these - share a wiki page on several Tiki sites, use all or 
part of a tracker data in another Tiki. Having an API will help remote 
and local Tiki share data.

In short, having an API won't automatically give us integrations with 
external software (like Slack you mentioned) but it will give us the 
possibility to integrate with external software. Some external software 
systems allow you to use events and send data to remote systems on 
certain events - these remote systems could be Tikies with proper API 
support.

HTH,
Victor

On 11/18/21 6:40 AM, Dr. Sassafras wrote:
> Let's see what victor says, but my understanding is the following:
>
> An API is simply a standard way to request or change information in 
> tiki. So we have our tiki interface. You can configure options and do 
> lots do stuff. All that stuff (potentially) can also be done from an 
> external system. The API does this.
>
> As per CalDAV. It might be better to use that than to reinvent the 
> wheel. Technically speaking we could make a Tiki API that does 
> everything CalDAV does. But the API we design would be non-standard. 
> So another program would need to be written on the other end to do 
> something useful with that data. So it is Kinda just a bad idea for 
> that reason and others.
>
> * add a user
> * see tracker data
> * post an article
> * modify a blog
> * delete a user
> * turn a preference on or off
> * add an item to the calendar
> * return all calendar events on this upcoming Tuesday.
> * tell me the last time a tracker was added
> * almost anything that tiki does
>
> Now there is a question of if some of these things should be in the 
> API. But the sky is the limit theoretically.
>
> Our pages could also retrieve data from an API, or something similar 
> to an API (AJAX calls). Right now the logic is not cleanly separated. 
> This won't concern you. (Internal vs external) You won't see a 
> difference. It is part of the huge job mentioned but gains nothing 
> tangible. It just plays a role in code maintainability, probability of 
> bugs, testing, etc.
>
> AJAX calls were never intended to be API calls, but they work 
> similarly. One of the big differences is that API calls always happen 
> from within tiki. So if we want to do something additional or have a 
> better way of doing something (refractor) we just do it and everything 
> works. But these changes will break connectivity with an outside 
> service that does not know things have changed. So you can get things 
> to “work” but may need to reconfigure somewhat complex requests the 
> next time you update. It could be a pain, especially when updating, 
> and could add to the cost, time and increase the level of expertise 
> needed to do an update. But the tradeoff is low initial expense.
>
> So I am leaving out a lot of technical stuff, but that’s what I have 
> to say. But also think about not only making API calls from other 
> applications but also from other TIki’s. Think about offline mobile 
> apps, what make calls when connected, etc. Or just mobile apps to do 
> something specific. Or versatile.
>
> API = Standard way to talking with Tiki. And everything needed to do 
> that well.
>
> Well, Victor. How did I do? Corrections?
>
> Brendan
>
>
>
>> On Nov 17, 2021, at 9:26 PM, Torsten Fabricius via TikiWiki-devel 
>> <[email protected] 
>> <mailto:[email protected]>> wrote:
>>
>>  Hi Victor,
>>
>> here my question:
>>
>> I understand an API as a tool for kind of *integrations*.
>>
>> Examples:
>> https://www.awork.io/en/integrations/
>> https://trello.com/integrations
>>
>> Is that about, what a Tiki API would be for and in which direction, 
>> as you distinguish between *internal and external services*?
>>
>> I am very interested in standart ways of connecting Tiki to other 
>> software to either use other software from Tiki - like our 
>> BigBlueButton video-conference-class-room (RoundTableMeeting) or the 
>> use of synched Tiki calendar data in desktop or phone apps using CalDav.
>>
>> Thinking about the term API, I have the idea, that a Tiki 
>> installation could be used as a Wiki, respectivels a knowledge-base 
>> tool for Nextcloud as it might become very easy to write a Nextcloud 
>> app using Tiki "services (?)".
>>
>> Or could a Tiki API be used to create a Slack integration for Tiki or 
>> a Tiki integration for Slack ... or maybe for Matrix?
>>
>> Could you please give (for non-coding consultants) a few more visual 
>> examples what we could do with a Tiki API please?
>> I am thinking about a few very brief use cases that help to 
>> understand what we are talking about. Thx.
>>
>> As you asked for feedback about a decision about the actual type of 
>> API, it would be helpful to get a picture what we could not do with 
>> an AJAX API but possibly with an API from scratch.
>>
>> The benefits and drawbacks of the AJAX type sound quite relevant, but 
>> I cannot really evaluate how relevant that would be for actual 
>> typical use cases.
>>
>> Thank you very much in advance.
>> And thx to you and the team for the work done until now.
>>
>> Torsten
>>
>>
>> Am 17.11.21 um 13:33 schrieb Victor Emanouilov via TikiWiki-devel:
>>> 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 
>>> <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. 
>>> 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] 
>> <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