Totara Learn Open Discussions

Replace Web services - External Service (deprecated)

 
Florent Plomb
Replace Web services - External Service (deprecated)
by Florent Plomb - Wednesday, 7 August 2024, 12:38 AM
Group Partners

Hi everyone,

I'm wondering how to replace my Totara web services - External Service (deprecated).

The use case is pretty simple: I need an API with 2 endpoints to do the following:

  1. Authenticate the user - currently, my External Service retrieves a token with basic auth (username and password) and the token is used for all subsequent requests.

  2. Get connected user info like: username, email, etc. (basic info of the user who makes the request, which we can identify based on the token).

What is the best way to achieve this with the recent versions of Totara 18+?

Thank you in advance for your help.

Craig Eves
Re: Replace Web services - External Service (deprecated)
by Craig Eves (Totara Support) - Tuesday, 13 August 2024, 6:25 PM
Group Totara

Hi Florent

We recommend using GraphQL API - there is a case study with code examples and documentation that should help .

The API Reference is available from your site under Development > API > API documentation

Let us know if you have any specific questions on applying this

Regards

Florent Plomb
Re: Replace Web services - External Service (deprecated)
by Florent Plomb - Wednesday, 14 August 2024, 1:17 AM
Group Partners

Hi Greg,

Thank you for the information. The GraphQL API seems the answer of everything by this time….

But I'd like to explain why I'm not entirely convinced by this approach.

In my original use case, I don't need to communicate through a new server-side app, or "client" as it's referred to in the documentation. The first step in the GraphQL setup, according to the documentation, is to "Register a client," which involves manually creating a new "client" (Quick-access menu > Development > API > Clients. Click the Add client). This means I have to create a new application, register it with Totara, and then build the logic to authenticate users and so on.

My main concern is that, unlike with a traditional web service, where I can simply create an endpoint on Totara and start using it directly, the GraphQL approach requires an additional step of setting up a "client." This essentially means having an extra application to serve as an intermediary or bridge to the API, which adds unnecessary complexity in my case.

In short, its requirement for a registered client makes it less straightforward for my specific needs, where a simple web service endpoint would suffice without the need for an extra application layer.


Craig Eves
Re: Replace Web services - External Service (deprecated)
by Craig Eves (Totara Support) - Wednesday, 14 August 2024, 1:38 PM
Group Totara

Hi Florent

You are right that GraphQL is more complex to setup than REST - it is suitable for large complex interrelated data sources.

Technically you don't need a GraphQL client to request data from a GraphQL endpoint all you need is a

POST request but a GraphQl client offers caching and other useful features

Regards


Florent Plomb
Re: Replace Web services - External Service (deprecated)
by Florent Plomb - Sunday, 18 August 2024, 11:50 PM
Group Partners

Hi Craig,

Just to clarify, the issue isn't about GraphQL vs. REST—both are just API architecture. The problem is with how Totara's new API (whether it's REST or GraphQL) requires a "client" to be registered before accessing any information. This means I can't directly use a user's credentials to authenticate and retrieve their data. Instead, I have to create and register an intermediary application (the "client") with its own specific authentication process, which adds unnecessary complexity for my use case.

Best,
Florent

Simon Coggins
Re: Replace Web services - External Service (deprecated)
by Simon Coggins - Monday, 19 August 2024, 6:04 PM
Group Totara

Hi Florent,

You are correct that there are some differences between the GraphQL and Webservices API in this regard.

The GraphQL API is currently designed to use a service account to execute requests, rather than assuming the role of the requesting user.

That said it would be possible to add per-user OAuth2 to provide individual user access in a secure way (known as 3-legged), it's just not something we've implemented support for in GraphQL yet.

The current web services approach, while simple, is not really great either - sending a username and password as API arguments is not best practice and wouldn't be compatible with many regulatory regimes.

GraphQL uses the industry standard OAuth2 client credentials approach which means you can use a short-lived token that will expire quickly if intercepted.


For your particular use case, and if you are comfortable with the security implications, there is nothing stopping you from continuing to use web services. While we won't be extending them any further we don't have any intention of removing them.

Simon