A comprehensive guide to building and consuming REST APIs in your APEX applications.
## Prerequisites
Before we dive into REST APIs with APEX, ensure you have:
- Oracle Database 19c or later (though earlier versions have REST capabilities, newer ones offer more features)
- APEX 21.1 or later (REST Data Source synchronization improvements are notable in later versions like 23.1+)
- Basic understanding of SQL and PL/SQL
- Foundational knowledge of REST concepts (Endpoints, HTTP Methods like GET/POST/PUT/DELETE, JSON format, Headers, Status Codes)
- Access to an APEX workspace
- Optional: Access to a target external REST API for consumption testing (e.g., a public API or a corporate API)
## Understanding REST API Integration Options in APEX
Oracle APEX provides robust capabilities for both *consuming* external REST APIs and *exposing* your own database objects (tables, procedures) as REST APIs. Here are the primary methods:
1. **REST Data Sources**: The modern, declarative way to *consume* external REST APIs. You define the endpoint and parameters, and APEX treats the response (usually JSON) like a table, allowing you to easily build reports, forms, and charts on remote data. Supports various authentication methods.
2. **APEX Web Service Modules (ORDS based)**: The primary way to *expose* your database data or logic as REST APIs. You define templates (URL patterns) and handlers (SQL queries, PL/SQL blocks) that execute when the endpoint is called. This relies on Oracle REST Data Services (ORDS) being configured with your database.
3. **`APEX_WEB_SERVICE` PL/SQL Package**: A powerful PL/SQL API for programmatically *consuming* external REST APIs. It gives you fine-grained control over request headers, bodies, security credentials, and parsing responses. Ideal for complex integrations or when the declarative REST Data Source isn't flexible enough.
4. **Legacy "Web Service References"**: An older method for consuming SOAP and REST services. Generally, REST Data Sources are preferred for new development involving REST.
## Consuming Your First External REST API (Using REST Data Sources)
Let's create a simple APEX application that fetches data from a public REST API using the declarative REST Data Source feature. We'll use the popular JSONPlaceholder API for demo purposes.
### Step 1: Identify a Public REST API
We'll use the JSONPlaceholder service, specifically the `/users` endpoint, which returns a list of dummy users in JSON format.
The endpoint URL is: `https://jsonplaceholder.typicode.com/users`
A successful `GET` request to this URL will return a JSON array of user objects. Here's a sample snippet of what the response looks like (showing the first user object in the array):
```json
[
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
},
{
"id": 2,
"name": "Ervin Howell",
"username": "Antonette",
"email": "Shanna@melissa.tv",
"address": {
"street": "Victor Plains",
"suite": "Suite 879",
"city": "Wisokyburgh",
"zipcode": "90566-7771",
"geo": {
"lat": "-43.9509",
"lng": "-34.4618"
}
},
"phone": "010-692-6593 x09125",
"website": "anastasia.net",
"company": {
"name": "Deckow-Crist",
"catchPhrase": "Proactive didactic contingency",
"bs": "synergize scalable supply-chains"
}
}
]
```
*(Note: The actual response contains more user objects in the array)*
### Step 2: Create a New Application
Begin by logging into your APEX workspace and creating a new application. Select "Create Application" and choose a blank application template. Name it `REST Demo` or something similar.
### Step 3: Create a REST Data Source
1. Navigate to **Shared Components** within your application.
2. Under "Data Sources", click on **REST Data Sources**.
3. Click the **Create** button.
4. Choose **From Scratch** and click **Next**.
5. Fill in the general details:
* **REST Data Source Type**: `Simple HTTP`
* **Name**: `JSONPlaceholder Users` (or a descriptive name)
* **URL Endpoint**: `https://jsonplaceholder.typicode.com/users`
6. Click **Next**. APEX will attempt to identify the Remote Server information. Review the Base URL and Service URL Path, then click **Next**.
7. Authentication is not required for this public API, so ensure "Authentication Required" is set to **No**. Click **Discover**.
8. APEX will now call the API endpoint. It analyzes the JSON structure (like the sample shown in Step 1) to identify potential data columns. Review the data profile preview it generates. You should see columns like `ID`, `NAME`, `USERNAME`, `EMAIL`, etc.
9. Click **Create REST Data Source**.
### Step 4: Create a Page to Display the API Data
1. Go back to your application's homepage in the App Builder.
2. Click **Create Page**.
3. Choose the **Report** page type.
4. Select **Interactive Report**.
5. Configure the page attributes:
* **Page Name**: `User List` (or similar)
* **Breadcrumb / Navigation**: Configure as desired.
6. Configure the data source for the report:
* **Source Type**: Select **REST Data Source**.
* **REST Data Source**: Choose the `JSONPlaceholder Users` source you created in Step 3 from the list.
7. Click **Next** and then **Create Page**.
8. Run the page by clicking the "Save and Run Page" icon (or navigating through your app menu).