diff --git a/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md b/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md index 55d6cd72..196bb84b 100644 --- a/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md +++ b/build-ords-apis-in-adb/1-create-user-and-database-objects/create-user-and-database-objects.md @@ -74,106 +74,127 @@ Estimated Lab Time: 20 minutes (click) Sample prompt

- ```sql - -- ========================================== - -- CREATE TABLES - -- ========================================== - CREATE TABLE DEPARTMENT ( - DEPT_ID NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, - DEPT_CODE VARCHAR(5) NOT NULL, - ESTABLISHED DATE, - DETAILS JSON - ); - - CREATE TABLE EMPLOYEE ( - EMP_ID NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, - EMP_NAME VARCHAR2(100) NOT NULL, - DEPT_ID NUMBER NOT NULL, - COMMENTS CLOB, - CONSTRAINT FK_EMPLOYEE_DEPT FOREIGN KEY (DEPT_ID) - REFERENCES DEPARTMENT (DEPT_ID) - ); + ```sql + -- ========================================== + -- CREATE TABLES + -- ========================================== + + -- DEPARTMENT table + + CREATE TABLE DEPARTMENT ( + DEPT_ID NUMBER GENERATED BY DEFAULT AS IDENTITY + CONSTRAINT DEPT_ID_PK PRIMARY KEY, + DEPT_CODE VARCHAR2(5) CONSTRAINT DEPT_CODE_NN NOT NULL, + ESTABLISHED DATE, + DETAILS JSON + ); + + CREATE UNIQUE INDEX DEPT_CODE_UK ON DEPARTMENT (DEPT_CODE); + + -- EMPLOYEE table + + CREATE TABLE EMPLOYEE ( + EMP_ID NUMBER GENERATED BY DEFAULT AS IDENTITY + CONSTRAINT EMP_ID_PK PRIMARY KEY, + EMP_NAME VARCHAR2(100) CONSTRAINT EMP_NAME_NN NOT NULL, + DEPT_ID NUMBER CONSTRAINT EMP_DEPT_ID_NN NOT NULL, + COMMENTS CLOB, + CONSTRAINT FK_EMPLOYEE_DEPT FOREIGN KEY (DEPT_ID) + REFERENCES DEPARTMENT (DEPT_ID) + ); + + CREATE INDEX EMP_DEPARTMENT_IX ON EMPLOYEE (DEPT_ID); + + -- PROJECT table CREATE TABLE PROJECT ( - PROJ_ID NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, - PROJ_NAME VARCHAR2(100) NOT NULL, - DEPT_ID NUMBER NOT NULL, - IS_ACTIVE BOOLEAN, - CONSTRAINT FK_PROJECT_DEPT FOREIGN KEY (DEPT_ID) - REFERENCES DEPARTMENT (DEPT_ID) + PROJ_ID NUMBER GENERATED BY DEFAULT AS IDENTITY + CONSTRAINT PROJ_ID_PK PRIMARY KEY, + PROJ_NAME VARCHAR2(100) CONSTRAINT PROJ_NAME_NN NOT NULL, + DEPT_ID NUMBER CONSTRAINT PROJ_DEPT_ID_NN NOT NULL, + IS_ACTIVE BOOLEAN, + CONSTRAINT FK_PROJECT_DEPT FOREIGN KEY (DEPT_ID) + REFERENCES DEPARTMENT (DEPT_ID) ); - -- ========================================== + CREATE INDEX PROJ_DEPARTMENT_IX ON PROJECT (DEPT_ID); + + -- ========================================== -- INSERT DATA - -- ========================================== - INSERT INTO DEPARTMENT (DEPT_CODE, ESTABLISHED, DETAILS) VALUES - ('HR001', DATE '2001-04-13', JSON_OBJECT('location' VALUE 'Bldg 1', 'members' VALUE 25)), - ('FN002', DATE '2002-06-20', JSON_OBJECT('location' VALUE 'Bldg 2', 'members' VALUE 20)), - ('EN003', DATE '2000-11-01', JSON_OBJECT('location' VALUE 'Bldg 3', 'members' VALUE 40)), - ('SA004', DATE '2005-01-15', JSON_OBJECT('location' VALUE 'Bldg 4', 'members' VALUE 18)), - ('MK005', DATE '2003-12-07', JSON_OBJECT('location' VALUE 'Bldg 5', 'members' VALUE 15)), - ('LG006', DATE '2010-03-31', JSON_OBJECT('location' VALUE 'Bldg 6', 'members' VALUE 5)), - ('IT007', DATE '2001-09-23', JSON_OBJECT('location' VALUE 'Bldg 7', 'members' VALUE 30)), - ('SP008', DATE '2015-05-05', JSON_OBJECT('location' VALUE 'Bldg 8', 'members' VALUE 12)), - ('LG009', DATE '2012-07-14', JSON_OBJECT('location' VALUE 'Bldg 9', 'members' VALUE 10)), - ('OP010', DATE '2008-08-01', JSON_OBJECT('location' VALUE 'Bldg 10', 'members' VALUE 22)); - - INSERT INTO PROJECT (PROJ_NAME, DEPT_ID, IS_ACTIVE) VALUES - ('Onboarding', 1, TRUE), - ('Audit2024', 2, FALSE), - ('NewApp', 3, TRUE), - ('SalesCampaign', 4, TRUE), - ('SocialMediaPush', 5, FALSE), - ('Compliance', 6, TRUE), - ('UpgradeInfra', 7, TRUE), - ('HelpdeskRevamp', 8, TRUE), - ('FleetUpdate', 9, TRUE), - ('ProcessReorg', 10, FALSE); - - INSERT INTO EMPLOYEE (EMP_NAME, DEPT_ID, COMMENTS) VALUES - ('Alice', 1, 'Strong analyst, quick learner.'), - ('Bob', 2, 'CPA certification in progress.'), - ('Carol', 3, 'Dev team lead for NewApp project.'), - ('David', 4, 'Consistent sales over target.'), - ('Eve', 5, 'Leads digital campaigns.'), - ('Frank', 6, 'Subject matter expert in compliance.'), - ('Grace', 7, 'Skilled in infrastructure upgrades.'), - ('Heidi', 8, 'Customer support supervisor.'), - ('Ivan', 9, 'Fleet manager - long tenure.'), - ('Judy', 10, 'Operations management veteran.'); - - -- ========================================== - -- PROCEDURE: PR_ADD_AND_ASSIGN_EMPLOYEE - -- ========================================== - CREATE OR REPLACE PROCEDURE PR_ADD_AND_ASSIGN_EMPLOYEE ( - p_emp_name IN VARCHAR2, -- Name of the new employee - p_dept_code IN VARCHAR, -- Department code to assign the employee to - p_comments IN CLOB -- Comments about the employee - ) AS - v_dept_id NUMBER; -- Variable to hold the found department ID - BEGIN - -- Attempt to look up the department's ID based on the provided department code - SELECT dept_id INTO v_dept_id - FROM DEPARTMENT - WHERE dept_code = p_dept_code; - - -- If a matching department was found, insert the new employee record - INSERT INTO EMPLOYEE (emp_name, dept_id, comments) - VALUES (p_emp_name, v_dept_id, p_comments); - - EXCEPTION - -- This block runs if no department matches the given code - WHEN NO_DATA_FOUND THEN - DBMS_OUTPUT.put_line('Department code not found.'); - - END; - - COMMIT; - / + -- ========================================== + INSERT INTO DEPARTMENT (DEPT_CODE, ESTABLISHED, DETAILS) VALUES + ('HR001', DATE '2001-04-13', JSON_OBJECT('location' VALUE 'Bldg 1', 'members' VALUE 25)), + ('FN002', DATE '2002-06-20', JSON_OBJECT('location' VALUE 'Bldg 2', 'members' VALUE 20)), + ('EN003', DATE '2000-11-01', JSON_OBJECT('location' VALUE 'Bldg 3', 'members' VALUE 40)), + ('SA004', DATE '2005-01-15', JSON_OBJECT('location' VALUE 'Bldg 4', 'members' VALUE 18)), + ('MK005', DATE '2003-12-07', JSON_OBJECT('location' VALUE 'Bldg 5', 'members' VALUE 15)), + ('LG006', DATE '2010-03-31', JSON_OBJECT('location' VALUE 'Bldg 6', 'members' VALUE 5)), + ('IT007', DATE '2001-09-23', JSON_OBJECT('location' VALUE 'Bldg 7', 'members' VALUE 30)), + ('SP008', DATE '2015-05-05', JSON_OBJECT('location' VALUE 'Bldg 8', 'members' VALUE 12)), + ('LG009', DATE '2012-07-14', JSON_OBJECT('location' VALUE 'Bldg 9', 'members' VALUE 10)), + ('OP010', DATE '2008-08-01', JSON_OBJECT('location' VALUE 'Bldg 10', 'members' VALUE 22)); + + INSERT INTO PROJECT (PROJ_NAME, DEPT_ID, IS_ACTIVE) VALUES + ('Onboarding', 1, TRUE), + ('Audit2024', 2, FALSE), + ('NewApp', 3, TRUE), + ('SalesCampaign', 4, TRUE), + ('SocialMediaPush', 5, FALSE), + ('Compliance', 6, TRUE), + ('UpgradeInfra', 7, TRUE), + ('HelpdeskRevamp', 8, TRUE), + ('FleetUpdate', 9, TRUE), + ('ProcessReorg', 10, FALSE); + + INSERT INTO EMPLOYEE (EMP_NAME, DEPT_ID, COMMENTS) VALUES + ('Alice', 1, 'Strong analyst, quick learner.'), + ('Bob', 2, 'CPA certification in progress.'), + ('Carol', 3, 'Dev team lead for NewApp project.'), + ('David', 4, 'Consistent sales over target.'), + ('Eve', 5, 'Leads digital campaigns.'), + ('Frank', 6, 'Subject matter expert in compliance.'), + ('Grace', 7, 'Skilled in infrastructure upgrades.'), + ('Heidi', 8, 'Customer support supervisor.'), + ('Ivan', 9, 'Fleet manager - long tenure.'), + ('Judy', 10, 'Operations management veteran.'); + + -- ========================================== + -- PROCEDURE: PR_ADD_AND_ASSIGN_EMPLOYEE + -- ========================================== + CREATE OR REPLACE PROCEDURE ORDS101.PR_ADD_AND_ASSIGN_EMPLOYEE ( + p_emp_name IN VARCHAR2, -- Employee's name to be inserted + p_dept_code IN VARCHAR2, -- Department code (case-insensitive search) + p_comments IN CLOB -- Additional textual comments about the employee + ) AS + v_dept_id NUMBER; -- Variable to store the department ID once found + BEGIN + + SELECT dept_id INTO v_dept_id + FROM DEPARTMENT + WHERE UPPER(dept_code) = UPPER(p_dept_code); + + + INSERT INTO EMPLOYEE (emp_name, dept_id, comments) + VALUES (p_emp_name, v_dept_id, p_comments); + + + EXCEPTION + + WHEN NO_DATA_FOUND THEN + DBMS_OUTPUT.put_line( + 'Department code (DEPT_CODE) not found. Please use one of the following:' || + ' EN003, FN002, HR001, IT007, LG006, LG009, MK005, OP010, SA004, SP008 ' + ); + + WHEN OTHERS THEN + DBMS_OUTPUT.put_line('Error: ' || SQLERRM); + + END; + / - ``` + ```

@@ -255,15 +276,26 @@ Estimated Lab Time: 20 minutes ![Unedited batchload curl command](./images-new/24-unedited-batchload-curl-command.png " ") -2. Retrieve the sample payload via [this link](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/batchload_directory.zip) that you'll use for testing this`BATCH LOAD` endpoint. Unzip the .zip file if this did not occur automatically. +2. Retrieve the sample payload via [this link](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/batchload_directory.zip) that you'll use for testing this `BATCH LOAD` endpoint. Unzip the .zip file if this did not occur automatically. 3. Once downloaded, copy the filepath details to use in the `--data-binary` option of the cURL command. In this example, the .csv file is located at: `/Users/me/Downloads/project_batchload.csv`. + > **IMPORTANT:** Your Command Prompt or Power Shell sample cURL Command may default to `-d` `--data` instead of `--data-binary`. Windows users should use a cURL command as seen in this example: + + ```shell + + curl -v -X POST ^ + -H "Content-Type: text/csv" ^ + "https://my-ocid-db-name.adb.my-region-1.oraclecloudapps.com/ords/ords101/project/batchload" ^ + --data-binary "@\Users\me\Downloads\project_batchload.csv" + + ``` + 4. In your text editor replace `` with `text/csv` and `--data-binary @` with your own file path. Optionally you may include other cURL options like those in the example. ![Edited batchload curl command](./images-new/25-batchload-curl-command-with-edits.png " ") - > **NOTE:** Your `BATCHLOAD` URI will differ as well. + > **NOTE:** Your `BATCHLOAD` URI will differ as well. File paths for macOS/Linux and Windows differ; double check your complete cURL command. 5. Execute the `BATCH LOAD` request. After a few moments the results of the operation will appear in your terminal. @@ -286,4 +318,4 @@ You may now [proceed to the next lab](#next). ### Last Updated By/Date -- Chris Hoina, September 2025 +- Chris Hoina, October 2025 diff --git a/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md b/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md index 06a92329..94f0e825 100644 --- a/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md +++ b/build-ords-apis-in-adb/2-build-ords-apis/build-ords-apis.md @@ -125,6 +125,7 @@ Estimated Lab Time: 25 minutes - **Module Name:** `records.module` - **Base Path:** `v1` + - **Protected By Privilege:** `Not Protected` (Select from drop-down) - **Comments:** `An employee records management module consisting of various templates and handlers for performing operations on the following target tables: Department, Project, Employee.` ![create-new-resource-module](./images-new/18-create-new-resource-module.png " ") @@ -163,27 +164,29 @@ Estimated Lab Time: 25 minutes ``` > **NOTE:** Notice how the the values for the Route Pattern are included in the Handler's source code. -5. You have just created your first ORDS API, a `GET` handler. Click the Open in new Tab button, you'll be prompted to enter in values for the Route Parameters. ORDS will bind these values of the URI to those in the Handler's SQL source code, satisfying the conditions of the `WHERE` clause. Select a `dept_id` between 1 and 10, and either true/false for the `is_active` parameter. Select **OK**. +5. You have just created your first ORDS API, a `GET` handler. Click the Open in new Tab button, you'll be prompted to enter in values for the Route Parameters. ORDS will bind these values of the URI to those in the Handler's SQL source code, satisfying the conditions of the `WHERE` clause. ![Adding details to the handler code](./images-new/23-finished-handler-code.png " ") +6. Enter a value between `1` and `10` for `dept_id`, and use either `true` or `false` (`BOOLEAN`) for the `is_active` parameter. Then, select **OK**. + ![Pressing OK for a new tab](./images-new/24-enter-substitution-pressing-enter.png " ") -6. A new browser tab will appear, with the results of your `GET` request. You can review the Response in the Object Tree format using your browser's developer/inspect tools. Notice the `links:Array` property; specifically the `self` link. Also, notice the URI includes those parameters you selected in the previous step (the same parameters that ORDS uses in the Handler source code). +7. A new browser tab will appear, with the results of your `GET` request. You can review the Response in the Object Tree format using your browser's developer/inspect tools. Notice the `links:Array` property; specifically the `self` link. Also, notice the URI includes those parameters you selected in the previous step (the same parameters that ORDS uses in the Handler source code). ![GET results in the browser](./images-new/25-new-browser-window-sql-get-results.png " ") -7. When you are ready, return the the Handler dashboard. You can test this API in cURL too. Click the kebab menu of your Handler, and select **Get cURL command**. +8. When you are ready, return the the Handler dashboard. You can test this API in cURL too. Click the kebab menu of your Handler, and select **Get cURL command**. ![curl-command-test](./images-new/26-curl-command-test.png " ") -8. Press the **+ plus** button, and enter in Substitution values for the cURL command (you can use the same ones as before). Then press **OK**. +9. Press the **+ plus** button, and enter in Substitution values for the cURL command (you can use the same ones as before). Then press **OK**. ![Press plus for substitution values](./images-new/27-press-plus-button-get.png " ") ![Press OK for substitution values](./images-new/28-new-values-before-press-ok.png " ") -9. Copy the cURL command, and paste it into a new Terminal window. You'll notice how your values have been appended to the URI of your ORDS API. Press **Enter** to execute the cURL command. +10. Copy the cURL command, and paste it into a new Terminal window. You'll notice how your values have been appended to the URI of your ORDS API. Press **Enter** to execute the cURL command. ![Copying the curl command](./images-new/29-copying-the-curl-command-for-get.png " ") @@ -191,13 +194,13 @@ Estimated Lab Time: 25 minutes > **NOTE:** You can optionally pipe in the `jq` processer to pretty print your `JSON` response. -10. You should see the response payload in your terminal. Scroll down, and you will see the rest of the payload. Because this is a large results set, you'll see a `next` link in the `links` array (unlike what you observed in the AutoREST lab). +11. You should see the response payload in your terminal. Scroll down, and you will see the rest of the payload. Because this is a large results set, you'll see a `next` link in the `links` array (unlike what you observed in the AutoREST lab). ![Get response part one](./images-new/31-get-response-one.png " ") ![Get response part two](./images-new/32-get-response-two.png " ") -11. In the next task you'll create a slightly more advanced `POST` endpoint. +12. In the next task you'll create a slightly more advanced `POST` endpoint. ## Task 4: Building an ORDS POST API @@ -298,4 +301,4 @@ You may now [proceed to the next lab](#next). ### Last Updated By/Date -- Chris Hoina, September 2025 +- Chris Hoina, October 2025