search

joomla / joomla-cms

Home of the Joomla! Content Management System
https://www.joomla.org
GNU General Public License v2.0
4.73k stars 3.64k forks source link

[RFC] Web Services or Joomla API? #31306

Open anibalsanchez opened 3 years ago

anibalsanchez commented 3 years ago

I've just realized that what people call Web Services, it is named "Joomla API" and the naming inconsistency is general.

Since "Joomla API" can refer to any API in Joomla (For instance, the Joomla Platform API), it would be great if we can avoid confusions naming web services as "Web Services". For more info about the definition of API as "application programming interface" https://en.wikipedia.org/wiki/API

Please, check the following inconsistencies between the official channels and the "Web Services" / "Joomla API" feature.

Joomla 4 tutorial: Using the Web Services API https://www.youtube.com/watch?v=lT9qodsvfZg

Joomla! Api https://docs.joomla.org/Category:Joomla!_Api

J4.x:Adding an API to a Joomla Component https://docs.joomla.org/Category:Joomla!_Api

Joomla Api Specification https://docs.joomla.org/Category:Joomla!_Api

J4.x:Joomla Core APIs https://docs.joomla.org/J4.x:Joomla_Core_APIs

Joomla Web Services API 101 - Tokens, Testing and a Taste Test https://magazine.joomla.org/all-issues/august-2020/joomla-web-services-api-101-tokens,-testing-and-a-taste-test

Web Services Working Group https://docs.joomla.org/Web_Services_Working_Group

On Joomla 4, there are plugins named:

  1. Web Services - Banners
  2. API Authentication - Basic Auth
  3. API Authentication - Joomla Token

In this case, it is not clear if all Joomla APIs of any kind are restricted with authentication, or only the Web Services are restricted with the "api-authentication" plugins.

So, it would be great if we settle to name web services as Joomla "Web Services" and remove all references to "Joomla API" or "API" to refer to "Web Services". In this way, the Joomla usage of the term "Web Service" will be close to the general usage of the concept. For more information about the "Web Service" term: https://en.wikipedia.org/wiki/Web_service

particthistle commented 3 years ago

I agree @anibalsanchez - when writing the JCM article it was a saga to find enough information, as well as know correct terminology to use (vs what had been implemented so far).

I propose a checklist to move forward with making the changes. Open to additions.

Confirm terminology

Joomla Docs

PR Required Adjust plugins to updated terminology:

Magazine Article

Joomla Docs Longer Term

Joomla 4.1 Enhancements

Official 3rd Party Integrations

Tags to add: Documentation Required, RFC

This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/31306.

anibalsanchez commented 3 years ago

Thinking in terms of the plugin names, it would be clearer:

We need to avoid the use of API. The regular Joomla user doesn't know what is an API. On top of this, API can refer to any API of the system. In all of these cases, we are talking only about "Web Services".

anibalsanchez commented 3 years ago

One more point, in the WordPress ecosystem, a similar feature to Joomla "Web Services" is named "REST API". API is qualified with "REST"; so the API is always going to be "RESTful Web services".

So, changing to "Web Services" on Joomla helps to differentiate the feature and define a wider scope for future development.

particthistle commented 3 years ago

Admin: Not sure why the label:RFC got dropped by the bot. @anibalsanchez do you want to add [RFC] to the subject line?

I've added :white_check_mark: to the items I've updated so far.

There's a few of the JDOCs that are going to need more of a coder's eye, as there's some function names and framework references that need refactoring to change what the impact may be of /api/ folder as an example.

zero-24 commented 3 years ago

I have just done the label and title stuff :+1:

anibalsanchez commented 3 years ago

@particthistle My report is about the displayed name in the user interface and in the documentation. It must be "Web Services".

There's no need for refactoring or complicating the issue. If coding people are happy calling Web Services as API internally, there is no issue with that.

laoneo commented 3 years ago

Is it only me, but Web Services is the wrong name. It is a Rest API. Not mor or less, or not? Web Services is too general...

anibalsanchez commented 3 years ago

"Web Services" is a more general concept than "Rest API"; it includes the "Rest API" as a special case. So, "Web Services" is not wrong. @laoneo

In the future, Joomla Web Services could also support SOAP APIs or GraphQL APIs.

brianteeman commented 3 years ago

@wilsonge a decision needs to be made on this before RC so we have time to update strings and docs if required

wilsonge commented 3 years ago

I'd prefer webservices I think as the term inside the CMS. We're not limited to just REST (even if that's what we are providing out the box). However the directory in the CMS should remain as API as by convention most websites use the /api/ path in their API urls

brianteeman commented 3 years ago

Based on this (https://en.wikipedia.org/wiki/Web_service) can we agree to go with "Web services"

jeckodevelopment commented 3 years ago

Based on the comments of Anibal, George and Brian, I would support "Web Services" too.

brianteeman commented 3 years ago

as #32496 has been merged shouldnt this be closed now or is there something outstanding?

particthistle commented 3 years ago

My checklist is a wider note on what else needs to be changed in regards to making Web Services something people uptake.

The issue @anibalsanchez has raised may be much simpler in regards to Joomla 4 changes, and may be able to see this issue closed.

The only suggestions remaining from @anibalsanchez's list are whether to rename these plugins:

Should these become:

anibalsanchez commented 3 years ago

@particthistle You are right in the sense that naming the plugins as Web Services Authentication would be much clearer. However, the plugin group has already be named as api-authentication. So, following the Joomla naming conventions for plugins the plugin group prefix must be API Authentication.

I think it would be better to name the plugins as: