Oracle Cloud Infrastructure Documentation

API Gateway QuickStart Guide

Find out how to get started quickly with API Gateway.

A. Set up your tenancy

1. Create groups and users

If suitable users and groups to create and access API Gateway and network resources don't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Domains.

  3. Create a new group by clicking Groups and then Create Group.

    This image shows the Create Group dialog, with empty Name and Description fields.

  4. Create a new user by clicking Users and then Create User.

    This image shows the Create User dialog, with empty Name, Description, Email, and Confirm Email fields.

  5. Add a user to a group by clicking Groups, then the name of the group, and then Add User to Group.

    This image shows the Add User to Group dialog, with an empty Users field.

See detailed instructions for more information.

2. Create compartment

If a suitable compartment in which to create API Gateway resources and network resources doesn't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Compartments.

  3. Click Create Compartment.

    This image shows the Create Compartment dialog, with empty Name and Description fields.

See detailed instructions for more information.

3. Create VCN and subnets

To ensure high availability, you can only create API gateways in regional subnets (not AD-specific subnets). If a suitable VCN with a public regional subnet in which to create network resources doesn't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu, click Networking, and then click Virtual cloud networks.
  3. Click Start VCN Wizard to create a new VCN.

  4. In the Start VCN Wizard dialog box, select Create VCN with Internet Connectivity and click Start VCN Wizard.

    This image shows the Start VCN Wizard dialog, with the "Create VCN with Internet Connectivity" option selected.

    As well as the VCN, the workflow creates a public regional subnet and a private regional subnet, along with an internet gateway, a NAT gateway, and a service gateway.

  5. Enter a name for the new VCN, and specify CIDR blocks for the VCN, the public regional subnet (must provide a minimum of 32 free IP addresses), and the private regional subnet.

    This image shows the Configuration page of the Create a VCN with Internet Connectivity workflow. The VCN CIDR Block, Public Subnet CIDR Block, and Private Subnet CIDR Block fields contain default values (10.0.0.0/16, 10.0.0.0/24, and 10.0.1.0/24 respectively).

  6. Click Next to review the details you entered for the new VCN, and click Create to create it. When the VCN has been created, click View Virtual Cloud Network to see the new VCN and the subnets that have been created.

    This image shows the Review and Create page of the Create a VCN with Internet Connectivity workflow, with all resources showing as having been created. The View Virtual Cloud Network button is shown.

    The API Gateway communicates on port 443, which is not open by default. You have to add a new stateful ingress rule for the public regional subnet to allow traffic on port 443.

  7. Click the name of the public regional subnet, then the name of the default security list, and then click Add Ingress Rules. Specify:
    • Source Type: CIDR
    • Source CIDR: 0.0.0.0/0
    • IP Protocol: TCP
    • Source Port Range: All
    • Destination Port Range: 443
    This image shows Add Ingress Rules dialog, with default values in all fields.
  8. Click Add Ingress Rules to add the new rule to the default security list.

See detailed instructions for more information.

4. Create IAM policies

If one or more API developers is not a tenancy administrator:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Policies.

  3. Create policies to give API developers access:

    This image shows Create Policy page, with all fields empty. The Show manual editor option has been selected.

    1. Create a policy with one policy statement to enable API developers to access API Gateway-related resources. Click Create Policy, specify a name and description for the new policy, and select the compartment that will own API Gateway-related resources. Use the Policy Builder Manual Editor to enter the following policy statement, and then click Create:
      Allow group <group-name> to manage api-gateway-family in compartment <compartment-name>
    2. Create a policy with one policy statement to enable API developers to access network resources. Click Create Policy, specify a name and description for the new policy, and select the compartment that owns the network resources to use with API Gateway. Use the Policy Builder Manual Editor to enter the following policy statement, and then click Create:
      Allow group <group-name> to manage virtual-network-family in compartment <compartment-name>

    Note: The above policies are sufficient to enable you to create an API deployment with an HTTP back end, as suggested in this QuickStart Guide. You can enter additional policies (as described in the documentation) to enable API developers to create API deployments with OCI Functions functions as back ends, and to enable API gateways to authenticate with a cache server to retrieve cached response data.

See detailed instructions for more information.

B. Create, deploy, and call your API

1. Create your first API gateway
  1. Sign in to the Console as an API Gateway developer, open the navigation menu and click Developer Services. Under API Management, click Gateways.
  2. Click Create Gateway and specify:
    • a name for the new gateway, such as acme-api-gateway
    • the type of the new gateway as Public
    • the name of the compartment in which to create API Gateway resources
    • the name of the VCN to use with API Gateway
    • the name of the public regional subnet in the VCN
    This image shows the Create Gateway dialog, with all fields empty by default, except for the Type field which is set to Public by default.
  3. Click Create.

    When the new API gateway has been created, it is shown as Active in the list on the Gateways page.

See detailed instructions for more information.

2. Create your first API deployment
  1. On the Gateways page in the Console, click the name of the API gateway you created earlier.
  2. Under Resources, click Deployments, and then click Create Deployment.

  3. Click From Scratch and in the Basic Information section, specify:

    • a name for the new API deployment, such as acme-api-deployment
    • a path prefix to add to the path of every route contained in the API deployment, such as /v1
    • the compartment in which to create the new API deployment

    This image shows the Basic Information page of the Create Deployment workflow, with the From Scratch option selected. Other fields are empty by default.

  4. Click Next and in the Route 1 section, specify:

    • a path, such as /hello
    • a method accepted by the back-end service, such as GET
    • the type of the back-end service, and associated details. For convenience, specify the type as HTTP and enter a public API as the back end's url (such as https://api.weather.gov).

    This image shows the Routes page of the Create Deployment workflow, with all fields empty by default.

  5. Click Next to review the details you entered for the new API deployment, and click Create to create it.

    This image shows Review page of the Create Deployment workflow. In the Basic Information section, the Name field contains acme-api-deployment, and the Path Prefix field contains /v1. In the Logging Policy section, the Execution Log Level field contains Information.

    When the new API deployment has been created, it is shown as Active in the list of API deployments.

  6. When the API deployment is active, go on to the next task.

See detailed instructions for more information.

3. Call your first API

  1. In the list of API deployments, click Copy beside the endpoint of the new API deployment you just created to copy the endpoint.

  2. Open a terminal window and call the API by entering:

    curl -k -X GET <deployment-endpoint>

    where <deployment-endpoint> is the endpoint that you copied in the previous step. For example, https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/v1/hello

Congratulations! You've just created your first API gateway and API deployment, and called your first API using the API Gateway service!

See detailed instructions for more information.

4. Next steps

Now that you've created, deployed, and called an API function, learn how to:

You're done!