Joomla Custom API Extension Setup Guide

Overview

The Custom API extension lets you create custom APIs to expand the capabilities of the Joomla CMS (Content Management System). By using these APIs you can expose particular features or data from your Joomla website, allowing external programs or services to communicate with your Joomla website. With the help of the custom endpoints you have developed, this plugin offers a smooth method to work with the Joomla database, enabling you to easily carry out CRUD (Create, Read, Update, and Delete) operations.

Download Plugin Pricing Plans Free Trial

Step 1: Installation of Custom API Extension

• Download the zip file for the miniOrange Custom API extension for Joomla from the link above.
• Login into your Joomla site’s Administrator console.
• From left toggle menu, click on System, then under Install section click on Extensions.

• Here click on Browse for file button to locate and install the extension file downloaded earlier.

• Once Installation of plugin is successful. Now click on Start Using Joomla Custom API plugin.

Step 2: Create Custom APIs

• GET
• POST
• PUT
• DELETE

Why use GET API

• If you want to retrieve data or information from your Joomla site, then you can create a GET API. You can add multiple filters and conditions to the get API using our plugin.
• When you make a GET request to an API, you can provide parameters or query strings in the URL to specify the data you want to retrieve from your Joomla site. The Joomla Custom API plugin then processes the request and returns the requested data in the response.

Configuration steps for creating custom GET API

• First navigate to the Create Custom API/SQL tab.
• Click on the Click Here button to create a new API.

• Enter an API Name and select the GET API method from the dropdown. Then, click the Create API button.

Configure API details

• Using Parameters
• Select the API type: By Parameters.
• Now select the table name on which you want to perform the data retrieve action.
• It will now show multiple options to select columns and filters for this API. Please specify the columns of the table from which you would like to retrieve data from the Joomla site. You can select the multiple columns here.
• Choose appropriate conditions and filters according to your requirements or you can opt for no condition as well. Click on + button if you want to add multiple WHERE conditions to filter out the data. You can remove the condition or filter as well by clicking the - button.
• Toggle on the Enable Authentication option if you want to enable Authentication on the API endpoint. (See Step 3 to learn how to setup API Authentication.)
• After configuring the API, click on Save button at last to create your Custom endpoint/REST API.

• Using Custom SQL API
• Select the API type: Custom SQL API.
• Write the Custom SQL Query that you want to execute on the successful API call. For example:

SELECT * FROM #__users WHERE id='{{id_param}}' AND email='{{email_param}}'; having _ is mandatory in the parameter name.



• Click on the Save button to create the custom API.

Why use POST API

• If you want to send data to your Joomla site to create resources on the site, then you can use the POST API.
• When you make a POST request to an API, you send data in the body of the request, typically in JSON or form-encoded format. The Joomla Custom API plugin then processes the data and performs the necessary actions based on the information provided in the request.

Configuration steps for creating custom POST API

• First navigate to the Create Custom API/SQL tab.
• Click on the Click Here button to create a new API.

• Enter an API Name and select the POST API method from the dropdown. Then, click the Create API button.

Configure API details

• Using Parameters
• Select the API type: By Parameters.
• Now select the table name on which you want to perform the data creation action.
• It will now show multiple options to select columns. Please specify the columns of the table from which you would like to retrieve data from the Joomla site. You can select the multiple columns here.
• Select the Body Data Format in which you want to send the data to the header from the dropdown.
• Toggle on the Enable Authentication option if you want to enable Authentication on the API endpoint. (See Step 3 to learn how to setup API Authentication.)
• After configuring the API, click on Save button at last to create your Custom endpoint/REST API.

• Using Custom SQL API
• Select the API type: Custom SQL API.
• You can make all parameters compulsory by enabling the checkbox. This feature requires all customer parameters to be passed on an API call.
• Write the Custom SQL Query that you want to execute on the successful API call. For example:

INSERT INTO #__users (id, name, username, email, registerDate, params) VALUES '{{id}}','{{name}}','{{username}}','{{email}}','{{registerDate}}','{{params}}';



• Click on the Save button to create the custom API.

Why use PUT API

• If you want to update or replace an existing resource on your Joomla site, then you can create a PUT API.
• When you make a PUT request to an API, you send data in parameters or query strings or in the body of the request to replace the entire representation of the resource identified by the request URL. The Joomla Custom API plugin then processes the data and updates the resource accordingly.

Configuration steps for creating custom PUT API

• First navigate to the Create Custom API/SQL tab.
• Click on the Click Here button to create a new API.

• Enter an API Name and select the PUT API method from the dropdown. Then, click the Create API button.

Configure API details

• Using Parameters
• Select the API type: By Parameters.
• Now select the table name on which you want to enter new data.
• Then select the columns for which you want to update using the API call.
• Choose appropriate conditions according to your requirements or you can opt for no condition as well. Click on + button if you want to add multiple WHERE conditions to filter out the data. You can remove the condition as well by clicking the - button.
• You have the flexibility to pass the data either as query parameters or within the body of the request.
• Ensure that you pass the data using the format key=Parameter Name(mentioned in Request Format and Conditions Applied table) and value=according to the specific requirements.
• To update user entry of above example you need to follow the following:
• Enter the URL: ‘{joomla_base_url}/api/index.php/v1/mini/custom_put’.
• Then select the PUT HTTP method.
• Pass data for name, username, param_1,param_2 in the body of the request(You can pass in the query format also).
• You will receive 1 in the response if data successfully updated in the table.

• Using Custom SQL API
• Select the API type: Custom SQL API.
• Write the Custom SQL Query that you want to execute on the successful API call. For example:

UPDATE #__users set username='{{username}}' where id='{{id}}';



• Click on the Save button to create the custom API.

Why use DELETE API

• If you want to delete a specific resource on your Joomla site, then you can create a DELETE API.
• When you make a DELETE request to an API, you can provide parameters or query strings in the URL or in the body of the request to specify the data you want to delete from your Joomla site. The Joomla Custom API plugin then processes the data and updates the resource accordingly.

Configuration steps for creating custom DELETE API

• First navigate to the Create Custom API/SQL tab.
• Click on the Click Here button to create a new API.

• Enter an API Name and select the DELETE API method from the dropdown. Then, click the Create API button.

Configure API details

• Using Parameters
• Select the API type: By Parameters.
• Now select the table name on which you want to perform the data delete action.
• Choose appropriate conditions according to your requirements or you can opt for no condition as well. Click on + button if you want to add multiple WHERE conditions to filter out the data. You can remove the condition as well by clicking the - button.
• Toggle on the Enable Authentication option if you want to enable Authentication on the API endpoint. (See Step 3 to learn how to setup API Authentication.)
• After configuring the API, click on Save button at last to create your Custom endpoint/REST API.

• Using Custom SQL API
• Select the API type: Custom SQL API.
• Write the Custom SQL Query that you want to execute on the successful API call. For example:

DELETE FROM #__users WHERE id='{{id}}';



• Click on the Save button to create the custom API.

Step 3: Configure API Authentication

• Bearer Token
• Basic Authentication
• API Key
• JWT Authentication

Bearer Token Authentication:

A simple token-based authentication where clients send a Bearer token in the Authorization header.

• First toggle on the Enable Authentication button in the Configure API Details section.
• In the Configure Authentication menu, select Bearer Token from the dropdown menu.
• Click on the Generate Token button to create a secure random token automatically. For example: 7c4a8d09ca3762af61e59520943dc26494f8941b
• Click "Save Configuration" to apply the Bearer token settings. The token will be stored securely in the database.

API Usage:

• Include the token in API requests:

Header: Authorization: Bearer 7c4a8d09ca3762af61e59520943dc26494f8941b



• Test the Bearer Token using the following cURL commands:

```bash
curl -X GET "https://yoursite.com/api/endpoint" \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json"

Test authentication using Postman:

• Open Postman.
• Set the request method and URL.
• Now, go to the Authorization tab.
• Select "Bearer Token" type.
• Then, enter your token in the Token field.

Basic Authentication (Joomla User Auth):

Uses existing Joomla user credentials (username/password) encoded in Base64 and sent via the Authorization header.

• First toggle on the Enable Authentication button in the Configure API Details section.
• In the Configure Authentication menu, select Basic Auth from the dropdown menu.
• No additional configuration is required, but the Users must exist in the Joomla User database.
• FInally, click on the Save Configuration button.

API Usage:

• Include Joomla username/password in API requests:

Header: Authorization: Basic base64(username:password)



• Test the Basic Auth using the following cURL commands:

```bash curl -X GET "https://yoursite.com/api/endpoint" \
-H "Authorization: Basic $(echo -n 'user:pass' | base64)" \
-H "Content-Type: application/json"

Test authentication using Postman:

• Open Postman.
• Set the request method and URL.
• Now, go to the Authorization tab.
• Select "Basic Auth" type.
• Enter the Joomla username and password.

API Key Authentication (Joomla User Auth):

Header-based authentication using API keys. Supports both universal keys (single key for all users) and user-based keys (individual keys per user).

• First toggle on the Enable Authentication button in the Configure API Details section.
• In the Configure Authentication menu, select API Key from the dropdown menu.
• Now choose the API Key Type.
• For Universal API Key:
• Select Universal API Key radio button.
• Click the Generate Universal API Key button.
• A single API key will be generated for all API access. For example: uk_7c4a8d09ca3762af61e59520943dc26494f8941b
• For User-based API Key:
• Select User-based API Key radio button.
• Generate keys for all existing Joomla users: Click Generate API Keys for All Users. Keys will be created for all active Joomla users.
• Generate key for specific user: Enter username in the "Username" field. Click Generate API Key for User.
• Click Save Configuration to apply API key settings.

API Usage:

• Include the API key in requests:

Header: X-API-KEY: <api_key>



• Test the API Key using the following cURL commands:

```bash
curl -X GET "https://yoursite.com/api/endpoint" \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json"

Test authentication using Postman:

• Open Postman.
• Set the request method and URL.
• Now, go to the Headers tab.
• Add header: Key = "X-API-KEY", Value = "your_api_key".

JWT Authentication:

JWT authentication allows you to authenticate the Custom REST API and Joomla default API endpoint access using a valid JWT token (JSON Web Token). The plugin provides an endpoint to generate a Bearer JWT using the valid user’s Joomla login credentials. The generated token can be used to authenticate the Custom and Joomla REST API endpoints.

• First toggle on the Enable Authentication button in the Configure API Details section.
• In the Configure Authentication menu, select JWT Bearer from the dropdown menu.
• Now choose the API Key Type.
• Select the Signing Algorithm from the dropdown menu.
• For HS256, enter the Secret Key.
• For RS256, upload the Public & Private Keys.
• Enter the expiry time (e.g 3600 for 1 hour).
• Click on the Save button.

To get the JWT Token, follow the following steps:

• To acquire the JWT, we must submit a POST query that contains the user’s Joomla credentials. The Username and Password must be sent in a base64-encoded format. For your convenience, please refer to the format of the request below.

Request: POST {joomla_base_url}/api/index.php/v1/mini/id_token
Header:
Authorization: Basic base64encoded
Accept: application/json
Sample curl Request Format-
--location --request POST "/api/index.php/v1/mini/id_token' \"
--header 'Accept: application/json'\
--header 'Content-Type: application/json' \
--header 'Authorization: Basic base64encoded’ \'

Step 4: Authentication for REST APIs

Configure authentication for Joomla's core APIs and APIs hosted on your Joomla site that will be automatically applied when these APIs are called.

• Go to the REST API Authentication tab.
• Enter the API Name and API Endpoint in the given fields.
• Then select the HTTP Method from the dropdown menu.
• Then toggle on the Enable Authentication button and select the authentication method of your choice. Refer to the Step 3 section of the guide to see how to configure the different authentication methods.

Step 5: Configure External APIs

• Go to the External APIs tab.
• Enter the API name.
• Then select the API Method from the dropdown.
• Enter the External API in the given field.
• You can pass query parameters which are necessary for this configured API. For the data to be sent in the query parameters format.
• There are 2 text fields - first is to enter the key and second one is to enter the value.
• For example→ If you have to pass the following query parameter ‘username→testuser’ then you need to put the ‘username’ in the key and ’testuser’ in the valuE field.
• You can add multiple parameters using + button.
• In the Headers, there are 2 text boxes - the left one is for the header name and the right one if for the header value that needs to be passed. For example : If the header passed to be in the format Authorization:Bearer then the ‘Authorization’ will be added in the first textbox and ‘Bearer should be put in the right textbox as shown in the diagram below.
• If the API provider expects the data needs to be sent in the body of the API endpoints request, then you can fill in the required details. There are 2 formats available in which you can send the data : x-www-form-urlencoded and JSON.
• For the data to be sent in the body parameters in x-www-form-urlencoded format.
• There are 2 text fields - first is to enter the key and second one is to enter the value.
• For example→ If you have to pass the following body parameter ‘username→testuser’ then you need to put the ‘username’ in the key and ’testuser’ in the value field.
• For the multiple key value pairs that need to be passed in the request body of the API endpoint request, you can click on the + button.
• For the data to be sent in the body parameters in JSON format: You need to select the JSON from the dropdown corresponding to the Request Body
• Now click on the Save Configuration button.

Related Articles

• Learn more about our Custom API extension.
• Real-Time Data Synchronization Between Joomla and a Custom Website.
• Implementing Secure JWT Authentication for Joomla Core APIs.