Building webservices

[woluweb]

A nice feature of Pages is that it can transform a blog (a collection) into JSON format.

Example

• blog version: https://www.joomlatools.com/blog/
• json version: https://www.joomlatools.com/blog.json

During JoomlaDay USA, this example was given:

• https://github.com/joomlatools/joomlatools-pages/blob/master/contrib/sites/blog/pages/blog/index.json.php

Is this feature already available in the current (0.20) version? Which formats are supported?

[johanjanssens]

Yes, for sure. Pages makes creating webservices with Joomla 3.x very easy.

A webservice as defined on wikipedia: "In a Web service a Web technology such as HTTP is used for transferring machine-readable file formats such as XML and JSON." Source: https://en.wikipedia.org/wiki/Web_service

Webservice features offered by Pages

1. Pages supports rendering to different machine readable formats: CSV, JSON, RSS, XML out of the box. Just create a page that defines the format you want to use, define a collection in it and Pages will render the data from the collection in that specific format. Examples:

• https://www.joomlatools.com/blog.json
• https://www.joomlatools.com/extensions/docman/changelog.json

2. Pages offers out of the box support for pagination, searching, filtering, sorting and sparse fieldsets, all are supported for any format, not only for JSONAPI.

3. Pages makes use of https://jsonapi.org/ for it's JSON webservice format. JSONAPI is a standardised format how to output JSON in a webservice that allows.

4. Pages can not only generate JSONAPI it can also read it and turn it into a collection on the fly. Pointing a webservice collection at at JSON API endpoint allows you to read that collection, no code required. This makes Pages out of the box interoperable with any webservice that uses the JSONAPI, for example, Drupal, Wordpress, or any other saas webservice.

5. Most Webservice are read only and not REST API's In Pages a webservice API endpoint is read/write and conforms to the REST API implementation. More info: https://en.wikipedia.org/wiki/Representational_state_transfer You cannot only retrieve data, you can also send data to it. This allows you to build micro-services with Joomla 3

6. Pages complies with Level 3 of the Richardson Maturity Model and offers a complete implementation of REST as defined by Roy Fielding

Differences with Joomla 4

The webservice implementation in Joomla 4 is more basic and is not RESTful, eg lack of caching and lack of uniform interface. Based on: https://docs.joomla.org/Joomla_Api_Specification these are some key differences.

• Implementation: In Joomla 4 you need to build a special plugin to integrate your own webservice. Pages does this out of the box.

• Routing: Joomla 4 uses a separate router for webservices, routes need to be registered through plugins and Joomla requires that all routes start with /api. Pages offers no-code, no-config routing that works everywhere and has no constraints on URL format, or endpoints. Any URL can be easily turned into a webservice. Pages gives you full freedom how your webservice URL's are routed.

• JSONAPI: Joomla 4 offers only basic support for JSONAPI with no support for pagination, sorting, searching, filtering, or sparse fieldsets.

• Caching: Joomla 4 doesn't offer any HTTP caching support. Pages is fully compliant wth the HTTP caching specification any supports both dynamic and static caching for webservices

• Content negotiation: Joomla 4 only offers support for negotiating content using application/json. Pages can negotiate content using url format suffix eg .json or using the Accept HTTP Header, offering support for HTML, JSON, JSONAPI, CSV, XML

• Language Negotiation: Joomla 4 doesn't offer support for language negotiating. Pages handles this out of the box.

• Richardson Maturity Model: Joomla 4 only complies with the Richardson Maturity Model level 1 and partly with level 2 (eg. lacks proper HTTP response code handling). Pages offers full compliance with the Richardson Maturity Model till level 3.

[woluweb]

Txs!
That feature will be fully functional in the next version, being 0.21. Correct?

[johanjanssens]

This is fully functional. There is only a small bug in 0.20.0/0.20.1 (it works in previous releases) related to the json output, I'm planning a maintenance release over the weekend to resolve that.

[alexandreelise]

Has this comparison changed since the release of J4RC1?

[johanjanssens]

Not that i'm aware of. A quick check shows they are working on JSONAPI filtering support but that hasn't made it in yet: joomla/joomla-cms#34288

The problem with the plugin approach in Joomla 4 is that you need to implement API support for a component through a custom plugin. Pages offers API support for any datasource transparently. This means that that JSONAPI support for the Joomla extension that is part of Pages offers a much more flexible and advanced API DSL in Joomla 3 than Joomla 4 is able to provide.

Take for example the filtering:

1. Pages support data filtering out of the box, regardless of the collection type, it works for database, webservice and for filesystem data sources.

2. Pages offers support for filter comparison operators, to allow to create very powerful filtering rules for data, you can even filter on dates.

3. Filters work both through URL, frontmatter and PHP code, provding a complete uniform API and DSL you can use everywhere.

Related PR's

• JSONAPI filter support #244
• Nested filter constraints #413
• Multiple filter constraints #301
• Multiple nested filter constraints  #477