Joomla-cms: [RFC] Web Services or Joomla API?

[anibalsanchez]

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]

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

• Use "Joomla! 4.x Web Services" for specific references to Joomla Web Services
• Use "Web Services" as the general reference to Joomla Web Services

Joomla Docs

• :white_check_mark: Create new JDOCS Category: "Joomla! 4.x Web Services" - https://docs.joomla.org/Category:Joomla!_4.x_Web_Services
• :white_check_mark: Add "Joomla! 4.x Web Services" and "Joomla! 4.x" to existing articles related to Web Services
• Update https://docs.joomla.org/Joomla_Api_Specification to swap API to Web Services
• Update https://docs.joomla.org/J4.x:Adding_an_API_to_a_Joomla_Component to swap API to Web Services
• Update https://docs.joomla.org/J4.x:Joomla_Core_APIs to swap API to Web Services
• Configure JDOCS redirects for old URLs for all of these articles.
• :white_check_mark: Configure redirect for old category to new category
• :white_check_mark: Revisit https://docs.joomla.org/Web_Services_Working_Group and reset category - added to new category.

PR Required
Adjust plugins to updated terminology:

• Web Services - Banners
• API Authentication - Basic Auth
• API Authentication - Joomla Token

Magazine Article

• @particthistle to edit article and update to new terminology https://magazine.joomla.org/all-issues/august-2020/joomla-web-services-api-101-tokens,-testing-and-a-taste-test

Joomla Docs Longer Term

• Add individual detail pages for each Web Service listed in https://docs.joomla.org/J4.x:Joomla_Core_APIs
• On individual detail pages, add example usage cases and complete mapping of field syntax that can be used for each Web Service request.

Joomla 4.1 Enhancements

• Improvements to Web Services Authentication to allow use by other ACL levels (currently only Super Users)
• Review Roadmap - is everything there?
• Are there other features that can be considered to include in Web Services for Joomla 4.1?

Official 3rd Party Integrations

• Zapier
• IFTTT
• Integromat

Tags to add: Documentation Required, RFC

---

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

[anibalsanchez]

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

• Web Services - Banners
• Web Services Authentication - Basic Auth
• Web Services Authentication - Joomla Token

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]

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]

_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]

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

[anibalsanchez]

@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]

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]

"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.