Adding a Function in OCI Functions as an API Gateway Back End
Find out how to create an API deployment with API Gateway that exposes serverless functions defined in OCI Functions.
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.
OCI 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 OCI Functions server. When a function is invoked for the first time, OCI 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, OCI 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 OCI Functions.
Before you can use serverless functions in OCI Functions as the back end for an API:
- Serverless functions referenced in the API deployment specification must have already been created and deployed in OCI Functions. The functions must be routable from the VCN specified for the API gateway, either through an internet gateway (in the case of a public API gateway) or through a service gateway (in the case of a private API gateway). See Creating and Deploying Functions. For a related Developer Tutorial, see Functions: Call a Function using API Gateway.
Appropriate policies must already exist that give access to serverless functions defined in OCI Functions to:
- a group to which your user account belongs (see Create a Policy to Give API Gateway Users Access to Functions)
- API gateways (see Create a Policy to Give API Gateways Access to Functions)
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 OCI Functions for Use as an API Gateway Back End
To create a serverless function in OCI Functions that can be invoked from an API gateway, follow the instructions in the OCI Functions documentation to:
- Confirm that you have completed the prerequisite steps for using OCI Functions, as described in Preparing for Functions.
- Create and deploy the function in a compartment to which API gateways have been granted access, as described in Creating and Deploying Functions.
Using the Console to Add Serverless Function Back Ends to an API Deployment Specification
To add an OCI Functions function back end to an API deployment specification using the Console:
-
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 an API Gateway or an API Deployment.
-
On the Authentication page, specify authentication options.
For more information about authentication options, see Adding Authentication and Authorization to API Deployments.
-
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:
- is relative to the deployment path prefix (see Deploying an API on an API Gateway by Creating an API Deployment)
- must be preceded by a forward slash ( / ), and can be just that single forward slash
- can contain multiple forward slashes (provided they are not adjacent), and can end with a forward slash
- can include alphanumeric uppercase and lowercase characters
- can include the special characters
$ - _ . + ! * ' ( ) , % ; : @ & =
- can include parameters and wildcards (see Adding Path Parameters and Wildcards to Route Paths)
- Methods: One or more methods accepted by the back-end service. For example,
GET, PUT
. -
Add a single backend or Add multiple backends: Whether to route all requests to the same back end, or to route requests to different back ends according to the context variable and rules you enter.
These instructions assume you want to use a single back end, so select Add a single backend. Alternatively, if you want to use different back ends, select Add multiple backends and follow the instructions in Using the Console to Add Dynamic Back End Selection to an API Deployment Specification.
- Backend Type: The type of the back-end service as
Oracle Functions
. - Application in <compartment-name>: The name of the application in OCI Functions that contains the function. You can select an application from a different compartment.
- Function Name: The name of the function in OCI Functions.
In this example, the route defines a simple Hello World serverless function in OCI Functions as a single back end.
Field: Enter: Path: /hello
Methods: GET
Backend Type: Oracle Functions
Application in <compartment-name>: acmeapp
Function Name: acme-func
-
- (Optional) Click Another Route to enter details of additional routes.
- Click Next to review the details you entered for the API deployment.
- Click Create or Save Changes to create or update the API deployment.
-
(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 GET 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 OCI Functions function back end to an API deployment specification in a JSON file:
-
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 theroutes
section. If you want to apply the policies just to a particular route, place the policies inside theroutes
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:- is relative to the deployment path prefix (see Deploying an API on an API Gateway by Creating an API Deployment)
- must be preceded by a forward slash ( / ), and can be just that single forward slash
- can contain multiple forward slashes (provided they are not adjacent), and can end with a forward slash
- can include alphanumeric uppercase and lowercase characters
- can include the special characters
$ - _ . + ! * ' ( ) , % ; : @ & =
- can include parameters and wildcards (see Adding Path Parameters and Wildcards to Route Paths)
<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 OCI Functions as a single back end:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- Save the JSON file containing the API deployment specification.
-
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 .
-
(Optional) Confirm the API has been deployed and that the serverless function in OCI 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 GET https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -d "name=john"