Re: [Tiki-devel] Tiki API discussion

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