documentation missing - FontAwesome::query()

This link on this page is 404

https://fortawesome.github.io/wordpress-fontawesome/classes/FortAwesome.FontAwesome.html#method_query

Searching google for FontAwesome::query() brings no love.

Also note, the documentation on the following pages may not be accurate (or PHP8.2 and WPengine may be at fault here)

https://docs.fontawesome.com/apis/graphql/get-started
Content-Type: application/json does not work

The following would have been super helpful to know.

$api_get = '/font-awesome/v1/api';
        $request = new WP_REST_Request( 'POST', $api_get );

        $request->set_header( 'content-type', 'application/graphql' ); // works
               // FAILS: $request->set_header( 'content-type', 'application/json' );

            /// all of these will fail with 'application/json' but work with application/graphql
        //$request->set_body( 'query { me { kits { token name } } }' );
        //$request->set_body( 'query { search (version: "6.0.0", query: "lightsaber", first: 5) { id } }' );
        $request->set_body( 'query { search (version: "6.0.0", query: "lightsaber", first: 15) { id unicode membership {free pro}   } }' );

        $response = rest_do_request( $request );

        if ( $response->is_error() ) { echo " failed"; print_r( $response );}

        if ( !$response->is_error() ) {
            echo "===worked=== ";
            $select2_json_data = $response->get_data();
            print_r( $select2_json_data );
            $headers = $response->get_headers();
            print_r( $headers );
        }
        exit();

I was able to find public function query( $request ) within class-fontawesome-api-controller.php which is what lead me to believe I should be using WP_REST_Request because class FontAwesome_API_Controller extends WP_REST_Controller

In closing:

FontAwesome::query() documentation would be good
showing working examples for WP_REST_Request on docs.fontawesome.com would be nice
Lost lots of life on this... time I will want back on my deathbed. (maybe blame php 8.2? anyway, "documentation missing => life missing")

PS: the WP plugin is super cool in all other regards. I have now read through most of the code, its nicely done.

Hi @zagarskas, sorry about the loss of life here.

That FontAwesome::query() function is definitely documented. But yeah, that link from the README is broken. Lame.

Seems like the document generator changed the path for that link at some point.

The best place to get into the PHP API docs is from the README here: readme

That links to the top-level of the generated PHP API docs here.

From there, those docs are navigable. So you could drill down to the FontAwesome::query() method here.

I fixed that link from the README as well.

documentation for the REST API route

The FontAwesome_API_Controller docs indicate how to POST a request to that route, but they don't indicate the content-type header expected. It expects just the default content-type, which according to MDN is: content-type: text/plain.

(But that's admittedly been implicit, and--to your point--it should be documented, thus saving life.)

(Side note: I've realized that the OWASP security rules used in mod_security for some Web Application Firewalls, doesn't like to see text/plain used for POST requests on this route. So I'm planning to change that in a future release. I think I can keep it backward compatible.)

public vs. private API

That "public" query() function you found in class-fontawesome-api-controller.php is not really public 😄

The doc comments on that function say:

Internal use only. This method is not part of this plugin's public API.

It's intentionally excluded from the API docs for that reason.

The public PHP API for query through this plugin is either:

the FontAwesome::query() function for which you hit that 404 page. I think its docs probably give you what you need.
the /wp-json/font-awesome/v1/api REST API route (See the FontAwesome_API_Controller doc for that.)

content-type header for WordPress REST API route versus api.fontawesome.com

What I infer from your original post is that you read the GraphQL API docs on fontawesome.com and saw the requirement to use content-type: application/json for that service. Then you tried to use content-type: application/json when sending a request to the plugin's REST API end, and it didn't work. Is that right?

If so, that's an understandable confusion.

The header content-type: application/json should indeed be used for any requests to the Font Awesome GraphQL API service at api.fontawesome.com.

And this WordPress plugin, on the back end, does issue queries to that api.fontawesome.com endpoint using application/json.

However, if you want to send a POST request to the WordPress REST API route on your own WordPress server at /wp-json/font-awesome/v1/api, then that end point does not expect application/json.

It expects a plain text GraphQL query document as a body of the POST request, not a JSON document. That's documented in the FontAwesome_API_Controller docs.

If you send a POST request to that WordPress REST API endpoint with content-type: application/json it won't work, which seems like what you discovered.

Summary

the doc link from the README to FontAwesome::query() is fixed
that function is the correct PHP API to use if you want to send a query through this plugin's PHP API
Or you could send a POST request to the /wp-json/font-awesome/v1/api route with a content-type: text/plain and a plain text GraphQL query as the body.
that internal controller query() method is not available as part of the public api
I intend to update the docs about that REST API endpoint to indicate the expected content-type header

FortAwesome / wordpress-fontawesome