Quick Start Guide

Getting started

We recommend a basic understanding of REST API’s and some of the terminology – here is a quick article on using REST API’s. The documentation for your API should also be followed.

In this guide, we will be using the Quotable API which is a free, open source API that will simply return a random quote for us. This is about as simple as an API can be. If you’ve never done anything with API’s before, this will be very easy to follow along.

Step 1. Setting up the API

After installing WPGetAPI and activating the plugin, click on the WPGetAPI link at the bottom of the sidebar. This will take you to the Setup page where you can add your first API.

There are 3 fields that are required:

• API Name – this can be whatever you like. The API is called ‘Quotable’, so this makes sense to name it the same.
• Unique ID – this can be whatever you like also. Must be lowercase letters only and underscores (no spaces). This ID is used within the shortcode or template tag to identify the API.
• Base URL – this is the base URL of the API, which can be found in your API’s documentation.

Once you have filled in all 3 fields, click the Save button and a new tab called Quotable will appear. Now click on this tab to be taken to the endpoint setup for this API.

Step 2. Setting up the endpoint(s)

In the documentation for your API you should see information about all of the endpoints that your API can connect to. In our case here, we are wanting to get a random quote so we will use the ‘random’ endpoint shown here – https://github.com/lukePeavey/quotable#get-random-quote

Lets look at the fields for connecting to our chosen endpoint:

• Unique ID – a unique ID for our endpoint. This unique ID will be used in the shortcode or template tag to identify this endpoint.
• Endpoint – this is the actual endpoint of the URL that will be appended to the Base URL that was setup earlier.
• Method – the request method for our endpoint. We need to use the GET request method.
• Results Format – the format of the data we receive back from the endpoint.
  • Data can be returned as either JSON string or PHP array.
  • The JSON string can be selected when using the shortcode or the template tag to display data.
  • PHP array data will return the data as a PHP array that can then be manipulated further (if you know basic PHP). This option can only be used with the template tag.

This is all the info we need for this API, so we can hit the Save button and we are now ready to test our endpoint.

Step 3. Testing the endpoint

Once the fields are filled in and you have saved the endpoint, you will see the Test Endpoint button become active. Clicking on this will call our endpoint and return some data as well as some extra debugging information. We are just concerned with the Data Output section and should see an array that contains our random quote.

Step 4. Displaying the API data

Our API is working correctly and it is returning the data we expect. We now want to display this on the front end of our website.

We have 2 options of how we can display the data – the template tag or the shortcode.

Whichever method you choose, you can simply copy either the template tag or the shortcode from the top of the endpoint that we just setup and add it to the appropriate place on your website.

4a. Using the template tag

The template tag is by far the most flexible option and will allow the most flexibility in formatting the data. The template tag allows you to get the results of the API call and put them into a variable which can then be used or manipulated however you choose. Some knowledge of PHP will be required for this.

At its simplest, you would add the template tag to one of your WordPress theme files where you want the API data to be displayed. In our example below, using the wpgetapi_pp() function will simply output the raw data from the API call.

// use the wpgetapi_endpoint() function to call our endpoint
// and save into the $random_quote variable
$random_quote = wpgetapi_endpoint( 'quotable', 'random' );

// use the wpgetapi_pp() function to output $random_quote
// as raw data
wpgetapi_pp( $random_quote );

To get the individual parts of the API response such as the author and the content, it would look something like the below.

// use the wpgetapi_endpoint() function to call our endpoint
// and save into the $random_quote variable
$random_quote = wpgetapi_endpoint( 'quotable', 'random' );

// display the content
echo $random_quote['content'];

// display the author
echo $random_quote['author'];

Please see the guide on using the template tag.

4b. Using the shortcode

You can add the shortcode into your pages and posts to output API data. This option is far more limited than using the template tag as the Results Format option must be set to JSON string.

Below we can see our shortcode pasted into a new page.

After adding the shortcode to the page, we can now view the page and see the results of the API call.

The result looks strange as this is basically the raw, JSON string that the API returns. Different API’s will return different types of data and if the API you are wanting to use does indeed return something similar to the below, then you would most likely need to use the template tag to be able to extract and format the data that you need. Another option could be to use the Pro Plugin which can extract individual pieces of data such as the ‘content’ as shown below, as well as being able to do some HTML formatting.

Please see the guide on using the shortcode.