Using the Webservices API to read an article Topic is solved

[davidascher]

I've been attempting to use the sample code in a module at
https://github.com/alexandreelise/Manua ... ervices.md
using the Joomla Framework to read the text of a specific article.

Things seem to go find until I get the response. It appears from this part of the response:

["reasonPhrase":"Laminas\Diactoros\Response":private]=>
string(9) "Not Found"
["statusCode":"Laminas\Diactoros\Response":private]=>
int(404)

I have tried getting the content of other articles by changing the articleId in my code, but I get the same result.

that the article I asked for was not found - however, I KNOW the article exists. Is there some common dumb mistake I might be making?

[pe7er]

Could you try to access the article using Postman and the Joomla 4 Web Services API Collection for Postman:
https://github.com/alexandreelise/j4x-api-collection

Or try Using the PHP cURL Functions:
https://manual.joomla.org/docs/general- ... -functions

[toivo]

This is an interesting topic! The Postman app worked all right when accessing a Joomla 5 article from a browser, as soon as the Joomla API token was set up as Bearer Token.

Also tested a quick and dirty custom component from Joomla 4 test site to display the text of an article from a Joomla 5 site using the PHP cURL functions, as documented in the link @pe7er posted.

[davidascher]

I can successfully read the contents of an article with cURL (I think I may have already written that). I can also read the contents of the same article with Postman. That would seem to indicate that everything is set up as it should be at the webservices server side. I think it is safe to assume that Postman does not use the Joomla Framework - and that's where I'm have a problem.

I am suspicious that variable $response in the line
$response = $http->request('GET', $uri, $dataString, $headers, $timeout)   ;
needs to be initialized as something that it is not currently. It is apparently a "Http Response Object". I cannot see how to see its contents. I am especially interested in the 'text' field but ... What am I missing?

[SharkyKZ]

Use $response->getBody() to read the body. It will be in the form of Psr\Http\StreamInterface object. Cast it to a string.

[davidascher]

I tried casting to string and still don't get a usable result from
$response->getBody()

The result of that is NULL.

I must still be missing something.

Things work perfectly using curl.

[toivo]

Can't you then just use the cURL method? It is not going to disappear overnight.

[davidascher]

This is an interesting topic! The Postman app worked all right when accessing a Joomla 5 article from a browser, as soon as the Joomla API token was set up as Bearer Token.

Also tested a quick and dirty custom component from Joomla 4 test site to display the text of an article from a Joomla 5 site using the PHP cURL functions, as documented in the link @pe7er posted.

Both Postman and your quick and dirty component are using curl. I thought the Joomla framework for webservices has been working for over a year and is well tested and reliable. It's not working for me. Only curl is working for me

[davidascher]

Can't you then just use the cURL method? It is not going to disappear overnight.

Yes, I could do that and will do that unless I have a sudden insight into why the webservices stuff isn't working for me. From what I've read, it has worked for other people - so why not for me?

[davidascher]

I've managed to get the GET and PATCH webservices working using the PHP Curl interface - no Joomla and now I have a related question.

I can see from the samples that I can request all the articles in a category by using something like:
https://test.peacecoalition.org/api/ind ... ategory]=2

Is 'category' the ONLY filter available?? it would be very nice to be able to retrieve articles filtered by other attributes - and/or to retrieve an article by its alias or by its name. I have tried
https://test.peacecoalition.org/api/ind ... alias-name'
and
https://test.peacecoalition.org/api/ind ... alias-name
and neither of those seem to do anything at all. I get back ALL the articles on the site.

Have I missed something? Is this kind of filter thing implemented ONLY for category (which should probably really have been catId)?

Is there documentation of this filter thing beyond its appearance in the sample code??

[davidascher]

I have apparently violated some forum rule by posting my last reply... I would be more than happy to do "the right thing", whether that is opening a new post, checking out the documentation (if I could locate it") or something else.

I find it difficult to understand the complete silence in response to my inquiry and equally difficult to believe that there is no way to retrieve the attributes of a articles filtered by attribute values other than category.

[SharkyKZ]

I'm guessing you your last post was a self-bump. A response is not guaranteed on this forum. Or it could be days, weeks, even months until someone decides to respond. In this case I think most people are in the same boat as you — sadly API filters are not documented anywhere, as far as I know. Anyways, these are the supported filters for articles: author, category, search, state, featured, tag, and language.

[davidascher]

SharkyKZ - thank you very much for breaking the silence. I'm not enough of a forum user to have intentionally 'self bumped' - but I now get the idea. Some people seem to know quite a bit about the Webservices stuff despite the lack of documentation. I presume they are either among the developers of this stuff or people who have spent much more time than most of us have poking around in the code and experimenting to figure out what kind of magic incantation they should send in a Webservices request to get anything beyond the same code examples to do what they want to do. I'd have sort of expected that somebody from one of those two cohorts would have written a (possibly impolite) note to let me know that what I was wanting to do cannot be done - yet? - or that it could be done and how to do it... Or at least a pointer to some presentation/documentation/video that explains it.

I understand that this is all voluntary and I don't have expectations that somebody owes me a response. I was just hoping that human decency and pride would be enough to stimulate responses from the appropriate individuals.

Now that we have that of of the way - I understand filter by author, category, state, featured, tag, and language. What is filter by "search"?? Does it search ALL the attributes of ALL the articles looking for a match to some string? Or just search the text attribute? What's the structure of a search request? (Can it be told in which attribute[s] it should search?)

How do you know this? The example code only shows filter by category. The rest seems to be up to the 'student' to figure out.

Thank you very much for your kind reply - and anything else you can share.

[pe7er]

Some people seem to know quite a bit about the Webservices stuff despite the lack of documentation. I presume they are either among the developers of this stuff or people who have spent much more time than most of us have poking around in the code and experimenting to figure out what kind of magic incantation they should send in a Webservices request to get anything beyond the same code examples to do what they want to do. I'd have sort of expected that somebody from one of those two cohorts would have written a (possibly impolite) note to let me know that what I was wanting to do cannot be done - yet? - or that it could be done and how to do it... Or at least a pointer to some presentation/documentation/video that explains it.

See Joomla Community Magazine:
https://magazine.joomla.org/all-issues/ ... api-part-1
https://magazine.joomla.org/all-issues/ ... api-part-2
https://magazine.joomla.org/all-issues/ ... api-part-3
https://magazine.joomla.org/all-issues/ ... api-part-4

or see https://slides.woluweb.be/ "Playing with the Joomla Web Services (API) in Joomla 4 or 5 or 6"

Now that we have that of of the way - I understand filter by author, category, state, featured, tag, and language. What is filter by "search"?? Does it search ALL the attributes of ALL the articles looking for a match to some string? Or just search the text attribute? What's the structure of a search request? (Can it be told in which attribute[s] it should search?)

The filters that you can use are the same as in the Joomla core code, e.g. the Articles Model:
https://github.com/joomla/joomla-cms/bl ... sModel.php

[Kubik-Rubik]

Hey David,

This is how you can use the HTTP class provided by the core for your API requests to retrieve the article text:

Code: Select all

$apiKey = 'API-KEY';
$apiUrl = 'https://DOMAIN/api/index.php/v1/content/articles/ARTICLE-ID';
$headers = ['X-Joomla-Token' => $apiKey];

try {
    $apiRequest = Joomla\CMS\Http\HttpFactory::getHttp()->get($apiUrl, $headers);
} catch (Exception $e) {
    // Error handling - Log error message
}

$returnCode = $apiRequest->getStatusCode();

if ($returnCode !== 200) {
    // Error handling - throw Exception() or log error message
}

$returnBody = $apiRequest->body;

if ($returnBody === '') {
    // Error handling - throw Exception() or log error message
}

$body = json_decode($returnBody, true, 512, JSON_THROW_ON_ERROR);

$articeText = $body['data']['attributes']['text'] ?? '';

Replace the placeholders in your code: API-KEY, DOMAIN and ARTICLE-ID

[Kubik-Rubik]

Optionally, you may use the getBody() method and cast it to a string:

Code: Select all

(string)$apiRequest->getBody()

[davidascher]

Victor - thank you for that sample code. I will give it a shot.

[davidascher]

I'm still unable to get ANY filter to work at all.
For example, I have tried using Postman with
https://t2.peacecoalition.org/api/index ... featured=1
or
https://t2.peacecoalition.org/api/index ... ewsletters
or anything else I could think of for the filter value and in every case I got back 20 articles and this

Code: Select all

  "links": {
        "self": "https://t2.peacecoalition.org/api/index.php/v1/content/articles?[filter]alias=newsletters",
        "next": "https://t2.peacecoalition.org/api/index.php/v1/content/articles?page%5Boffset%5D=20&page%5Blimit%5D=20",
        "last": "https://t2.peacecoalition.org/api/index.php/v1/content/articles?page%5Boffset%5D=560&page%5Blimit%5D=20"
    }

As far as I can tell the filter in my request was completely ignored and ALL the articles would eventually be retrieved if I followed the "next" links. Is there still something I am doing incorrectly when I submit my innitial request? I'm guessing that the limit to 20 articles at a shot is a Postman thing... but I have ONLY ONE Article with the alias "newsletters" and that's the only one I want to retrieve.

[SharkyKZ]

It should be filter[featured], not [filter]featured.

[Kubik-Rubik]

Hey David,

you are welcome. As SharkyKZ said, you need to send the query parameter properly.

Example:

Code: Select all

?filter[tag]=Joomla

You may set the following filter elements:

Code: Select all

author
category
search
state
featured
tag
language

Example code for all featured and published articles with the tag Joomla from the author with the ID 42:

Code: Select all

DOMAIN/api/index.php/v1/content/articles?filter[tag]=Joomla&filter[author]=42&filter[featured]=1&filter[state]=1

Replace the placeholder DOMAIN with your domain.

Have success!

[davidascher]

Hey David,

you are welcome. As SharkyKZ said, you need to send the query parameter properly.

Example:

Code: Select all

?filter[tag]=Joomla

You may set the following filter elements:

Code: Select all

author
category
search
state
featured
tag
language

Thank you very much for this information! Other than through examining the code (and understanding it) how would somebody know this??

It seems a pity that one cannot retrieve a single article by its name or alias. That seems not unreasonable for the human interface (listing articles in the backend) but for the Webservices API I'd have expected to see at least get article by alias. I suppose that could be done with a little override - if one could figure out how the code actually works.

[Kubik-Rubik]

You are welcome!

For the alias, you may use the normal search filter:

Code: Select all

DOMAIN/api/index.php/v1/content/articles?filter[search]=newsletters

[Kubik-Rubik]

By the way, the search filter is quite powerful. You may define a specific article directly using the id: prefix.

Code: Select all

DOMAIN/api/index.php/v1/content/articles?filter[search]=id:X

Replace X with the correct ID of your newsletter article.

A list of possible prefixes:

Code: Select all

id:
author:
content:

Have success!

[davidascher]

By the way, the search filter is quite powerful. You may define a specific article directly using the id: prefix.

Code: Select all

DOMAIN/api/index.php/v1/content/articles?filter[search]=id:X

Given that there is already the possibility of using

Code: Select all

DOMAIN/api/index.php/v1/content/articles/articleId

Why would anybody want to use a filter like that?

[Kubik-Rubik]

Why would anybody want to use a filter like that?

This feature was implemented for the search in the UI. You can use the search to filter by IDs with this prefix. So, this prefix also works in the API.

[davidascher]

You are welcome!

For the alias, you may use the normal search filter:

Code: Select all

DOMAIN/api/index.php/v1/content/articles?filter[search]=newsletters

This request would return all articles with the string "newsletters" in their name or alias. Additional filtering by category or author could narrow it down, or additional code after the response comes back could do that, but it seems to me that the most common use case would be search for an exact match (to an alias at least). Unless there are additional arcane incantations available to to that, this seems to me to be a most useful addition for the next version of Joomla webservices.

Thank you again for putting up with my questions.

[davidascher]

It STILL seems a pity that one cannot retrieve a single article by its EXACT name or alias. Returning all articles with a substring match seems not unreasonable for the human interface (listing articles in the backend) but for the Webservices API I'd have expected to see at least get article by EXACT alias - and/or maybe with wildcard capabilities. I suppose that could be done with a little override - if one could figure out how the code actually works.

It also seems that if you have an /content/articles/articleId it's not likely that anybody is going to want to use /content/articles?filter[search]=id:X. Perhaps it wouldn't be difficult to extend the webservices to support
/content/articles/alias similar to how /content/articles/articleId is implemented. If the 'basename' is numeric, then it is an articleId; if it is alphanumeric then it is an alias.

[Kubik-Rubik]

What's wrong with using the article's ID directly instead of the title or alias?

PS: You don't need to use the prefix filter (?filter[search]=id:X) to retrieve a specific article, always prefer the corresponding endpoint for it. It was just an example to show you what is possible with the search filter parameter.

[davidascher]

Shouldn't a request with a bad value for filter return some kind of error indication? For example,

Code: Select all

https://test.peacecoalition.org/api/index.php/v1/content/articles?filter[title]=newsletters

does not return an error. I understand that 'title' is not supported. For webservices to be ready to unleash on an unsuspecting public, I'd have expected it to be a bit more bulletproofed - some return message like 'invalid filter' or something. Instead, it returns all the articles (unfiltered) as if there is no problem.

Are you two guys part of the team that worked on the webservices implementation? I'd be happy to submit a "formal suggestion for improvement" if there is a mechanism for doing that.

[SharkyKZ]

You can submit the suggestion on the issue tracker https://github.com/joomla/joomla-cms/issues.