Oracle Cloud Infrastructure Documentation

Adding a Function in Oracle Functions as an API Gateway Back End

A common requirement is to build an API with serverless functions as a back end, and an API gateway providing front-end access to those functions.

Oracle Functions enables you to create serverless functions that are built as Docker images and pushed to a specified Docker registry. A definition of each function is stored as metadata in the Oracle Functions server. When a function is invoked for the first time, Oracle Functions pulls the function's Docker image from the specified Docker registry, runs it as a Docker container, and executes the function. If there are subsequent requests to the same function, Oracle Functions directs those requests to the same running container. After a period being idle, the Docker container is stopped.

Having used the API Gateway service to create an API gateway, you can create an API deployment that invokes serverless functions defined in Oracle Functions.

Before you can use serverless functions in Oracle Functions as the back end for an API:

You can add serverless function back ends to an API deployment specification by:

  • using the Console
  • editing a JSON file

Creating and Deploying a Serverless Function in Oracle Functions for Use as an API Gateway Back End

To create a serverless function in Oracle Functions that can be invoked from an API gateway, follow the instructions in the Oracle Functions documentation to:

Using the Console to Add Serverless Function Back Ends to an API Deployment Specification

To add an Oracle Functions function back end to an API deployment specification using the Console:

  1. Create or update an API deployment using the Console, select the From Scratch option, and enter details on the Basic Information page.

    For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating API Gateways and API Deployments.

  2. On the Routes page, create a new route and specify:

    • Path: A path for API calls using the listed methods to the back-end service. Note that the route path you specify:

    • Methods: One or more methods accepted by the back-end service. For example, GET, PUT.
    • Type: The type of the back-end service as Oracle Functions.
    • Application in <compartment-name>: The name of the application in Oracle Functions that contains the function. You can select an application from a different compartment.
    • Function Name: The name of the function in Oracle Functions.

    In this example, the route defines a simple Hello World serverless function in Oracle Functions as a single back end.

    Field: Enter:
    Path: /hello
    Methods: GET
    Type: Oracle Functions
    Application in <compartment-name>: acmeapp
    Function Name: acme-func
  3. (Optional) Click Another Route to enter details of additional routes.
  4. Click Next to review the details you entered for the API deployment.
  5. Click Create or Save Changes to create or update the API deployment.
  6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

    If the serverless function accepts parameters, include those in the call to the API. For example:

    curl -k -X POST https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -d "name=john"

Editing a JSON File to Add Serverless Function Back Ends to an API Deployment Specification

To add an Oracle Functions function back end to an API deployment specification in a JSON file:

  1. Using your preferred JSON editor, create the API deployment specification in a JSON file in the format:

    {
      "requestPolicies": {},
      "routes": [
        {
          "path": "<api-route-path>",
          "methods": ["<method-list>"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "<identifier>"
          },
          "requestPolicies": {}
        }
      ]
    }

    where:

    • "requestPolicies" specifies optional policies to control the behavior of an API deployment. If you want to apply policies to all routes in an API deployment specification, place the policies outside the routes section. If you want to apply the policies just to a particular route, place the policies inside the routes section. See Adding Request Policies and Response Policies to API Deployment Specifications.
    • <api-route-path> specifies a path for API calls using the listed methods to the back-end service. Note that the route path you specify:

    • <method-list> specifies one or more methods accepted by the back-end service, separated by commas. For example, "GET, PUT".
    • <identifier> specifies the OCID of the function you want to use as the back-end service. For example, "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq".

    For example, the following basic API deployment specification defines a simple Hello World serverless function in Oracle Functions as a single back end:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Save the JSON file containing the API deployment specification.
  3. Use the API deployment specification when you create or update an API deployment in the following ways:

    • by specifying the JSON file in the Console when you select the Upload an existing API option
    • by specifying the JSON file in a request to the API Gateway REST API

    For more information, see Deploying an API on an API Gateway by Creating an API Deployment .

  4. (Optional) Confirm the API has been deployed and that the serverless function in Oracle Functions can be invoked successfully by calling the API (see Calling an API Deployed on an API Gateway).

    If the serverless function accepts parameters, include those in the call to the API. For example:

    curl -k -X POST https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -d "name=john"