JetEngine recently got an update, and now it provides vast opportunities to work with REST API. This article will go through examples of their use cases and, of course, a bit of theory.
What the REST API is
Let’s start over with the basics. API stands for Application Programming Interface, and it’s that something that allows software components to “communicate” with each other. API can be anything and in any form like a set of ready-made classes, functions, procedures, structures, and constants. The only condition is that it should provide data and functionality from your apps so developers and applications can access it. There are multiple ways to design an API, and REST is the one to do it faster and in a way third-parties will understand better.
REST API is an API built on the REST specification guidelines. REST (or RESTful) stands for REpresentational State Transfer, and these are the general principles of organizing the interaction of an application/site with a server using the HTTP protocol. The peculiarity of REST is that the server does not remember the user’s state between requests – each request contains information that identifies the user (for example, a token obtained through 0Auth authorization) and all the parameters required to perform the operation.
How REST API works
REST API uses HTTP requests to URLs that return custom responses. All interaction with the server is reduced to 4 operations:
1. GET – receiving data from the server (usually in JSON or XML format)
2. POST – adding new data to the server
3. PUT – or update – editing the existing data on the server
4. DELETE – deleting data on the server
There are two main reasons for REST API’s popularity – simultaneous stability and flexibility. REST API uses HTTP, which distinguishes it from other API types that require developers to define a protocol for their creating and functioning. And it’s flexible since it can handle different call types and returns in various data formats like XML, JSON, YAML, etc.
WordPress REST API
The WordPress REST API allows access to your WordPress site’s content and functionality via HTTP and JSON. To be specific, WordPress REST API provides REST endpoints (URLs) that hold down the posts, pages, taxonomies, and other WP data types.
Actually, REST is one of many APIs that WordPress provides, but it’s the only one that can return JSON. Follow this link if you’d like to find out more about other WordPress APIs.
WordPress REST API features
You already know that REST API’s primary function is to represent WordPress content in JSON format, but the list is not limited to this. What else REST API can do:
- Allows to control content and some settings: to edit them, delete, or add new
- Provides access to templates, themes, and plugins inside of WordPress
- Provides access to websites and applications outside of WordPress
- Allows to customize and extend core REST API functionality via special plugins
Go to the REST API Handbook to find out everything about the WordPress REST API.
JetEngine’s REST API features
In the latest release, JetEngine 2.6, we’ve launched various opportunities to work with REST API. For now, our dev team realized three significant features:
- REST API Endpoints for the Custom Content Type. Now you can enable and disable support of various JSON REST API endpoints for CCT. These endpoints allow you to get a list of items of the selected CCT, add new items, edit or delete existing ones through the REST API.
Follow this link to our knowledge base to find out how to add and edit CCT items remotely using REST API.
- REST API Listings. It is a separate module, and it enables displaying data from third-party REST API via the Listing Grid widget.
How to enable the connection with the endpoint – knowledge base.
- REST API Request notifications for Forms. We have added a new type of notification, and now you can specify the URL, and it will transfer the data of the form to it. You can further adjust the authorization parameters, customize the request body, and configure the request’s dynamic URL. This notification is only added when the REST API Listings module is activated.
How to connect the form to CREATE item REST API endpoint – knowledge base.
How to use JetEngine as a WordPress Rest API plugin
Now let’s dive into the real-life examples of use. Andrew Shevchenko, CTO of Crocoblock, held the latest JetTalks to uncover the use-cases of working with JetEngine REST API. Here’s the full version:
Below is a short printed version of what Andrey told in the video. Please pay attention to the links attached to the Steps – they lead to the timestamp in the video showing how to perform these steps.
Use-case #1: Exchanging data on the back-end via a POST request
As we know, API is used to let the sites interact with each other, share and display data and content. A trivial example – the WordCamp central site and its major events’ separate websites like WordCamp Europe 2020 or WordCamp Mexico 2020. The central site contains general information and a timetable, while the event sites have detailed information about a specific event. At the same time, each event site transmits data to the general site through the API. For example, this is how an event visitor base assembles to make personalized email newsletters.
In our case, let’s imagine that we also have a Central site and an Event site. The Central site contains a Custom Content Type (CCT) with the list of participants of all events and a form for adding new items to this CCT.
The task is to create the submission form on the Event site to collect new participants and connect it to the CCT of the Central site to store our new participants there. And here is the new functionality of JetEngine that comes to our aid.
Step 1: Creating item endpoint
Here we will use our newly launched feature REST API Endpoints for the Custom Content Type. To add REST API Endpoint:
- Go to JetEngine → CCT settings → activate the ‘Register create item REST API Endpoint’ option.
The Endpoint URL that you see on the screenshot appears right after the activation. By sending a POST request to this URL, we will add a new item to the CCT Form Submissions. Any application, PHP code, or any service that allows sending POST requests can send this request.
Now we need to restrict access to this endpoint.
- Specify the default value or the custom capability from the list of all registered WordPress core capabilities in the Access Capability field.
For example, if set manage_options capability, only users with permission to change site options will have access.
Now we can send data to our Central site via the REST API.
Step 2: Creating a form with a new notification on the Event website
Our next stop is to create a form on the Event website that can use this endpoint. Follow this link to the tutorial on how to create a form with JetEngine.
After building the form, we need to add a new notification to this form – REST API Request.
- Go to the form’s settings page → Post-submit Actions → enter the URL of our endpoint.
This notification will send all form data using a POST request to the specified URL when submitting the form.
Step 3: Authorizing of the request
The only issue left is that this REST API Endpoint will allow submitting new CCT items only for users with a specific capability (manage_options in our case). We have to specify the appropriate authorization parameters for this request so that the Central site will accept our POST request. To do this:
- Tick/activate the Authorization option in the notification settings.
This option allows you to configure the authorization parameters for the request. For now, only the Application Password authorization type is available, but we’re going to add other ones in future updates.
Now we need to specify the application user and password. We can get them from the Central site. As there’s no such functionality in the WordPress core, we will use a free third-party plugin, Application Passwords, to create this password for our User.
- Go to the User Settings page → Application Passwords section → add a new password.
- After the password was generated, copy it and add it with the user name to the form’s authorization settings.
From now, when the API request is sent, the Central site will recognize which user is trying to submit this request and grant him access.
Step 4: Defining the form submission source
At the moment, the event itself isn’t specified in our Event submission form.
- Go to Edit Form → Fields Settings → Add Field
Since in our case, all users who submit the form on the Event website will attend the only event, we can just fill in the necessary fields manually.
Step 5: Adding the form to the front-end
After we adjusted everything from the back-end, it’s time to edit our form with Elementor. All you have to do is drag and drop the Form widget to the page’s canvas and select the form you have just created. Find out the detailed tutorial by following this link.
After the form is successfully implemented on the website, new users who submit the form on the Event website will be automatically stored on the Central website.
Use-case #2: Displaying data on the front-end via GET request
Here is the screenshot from the WordCamp Finland site that displays its list of attendees. Users who submit the form on this site appear on the public page, and it also happens thanks to API. Let’s figure out how to enable this option with JetEngine REST API functionality.
Step 1: Getting items endpoint
Here we face the same issue as in the previous case – the list of participants is physically located on the Central site while we want to display it on the Event site. To resolve it, we will use the GET API request.
- Go to CCT settings → Form Submissions → activate the option Register get items/item REST API Endpoint.
We can also restrict access by filling in the required value to the Access Capability field, but it isn’t necessary for our current project.
Everything is quite similar to the previous case – we see the URL of this endpoint and settings for restricting access. The only difference is that this time we have two URLs:
1) to get all items list
2) to get a single item by its ID
So, if we insert the URL of this endpoint into the browser bar, we will get specific data:
Unfortunately, it’s challenging to use it efficiently in such a form, but the module REST API Listings will help us here again.
Step 2: Creating a new REST API endpoint
The REST API Listing module’s main functionality allows you to register endpoints from any third-party resources and display information from them using the Listing Grid widget.
- Go to JetEngine dashboard → REST API Endpoints → Add new endpoint.
The foremost part we need to do here is to fill in the API Endpoint URL. The Name field is necessary just for your convenience, so it’s ok to choose any.
Here we find a crucial function – Items path.
This function allows JetEngine to find the items list in the REST API response. The problem is that different REST APIs have a different structure of the response, and it’s not always just an array of items, so this option helps to determine where exactly we can find a variety of required items inside the REST API response. In our case, the response from REST API contains only an array of items and nothing else, so we can leave this field empty.
Now the only thing left to create a new endpoint is to check if our website is connected to this REST API endpoint, i.e., if the site will get data from this URL.
- Send Request → Get the status ‘Connected’ (or you will receive the response from the system explaining what’s wrong with the URL) → Save
So, now we created the new endpoint.
Step 3: Creating a listing item and outputting it on the front-end via the Listing Grid widget
Now we have to create a new listing item to display our participants on the front-end.
- Go to Listings → Add New → select the parameters → Create Listing Item.
A full tutorial on creating a new listing item and displaying it on the website is here.
Step 4: Filtering out the displayed participants
We did everything needed, but now all the people whose data is stored in the CCT are visible on the site. We need to make sure that only visitors of a particular event are displayed in this list. So, we have to set the right Query Arguments.
- Go to Custom Content Types list → Form Submissions → Endpoint URL Parameters Overview.
We’ll see the list of GET endpoint parameters available for this REST API endpoint. In our case, we need the parameter ‘event.’
- Go to the Listing settings → REST API Query section.
Fill in this field with a parameter name and parameter value separated with ‘=.’
So, now we’re done. We displayed on the Event site the list of participants of the particular event physically located on the Central site with the help of REST API.
A full guide on displaying the items obtained via REST API in Elementor and Gutenberg is here.
I hope I managed to explain not much worse than Andrew. ? If you have any questions, write them in the comments, and we will be happy to answer everything.
So, have you already used the new JetEngine REST API functionality? Was it convenient enough? We’re looking forward to your feedback!