Creating an API Deployment Specification

To create an API deployment specification whilst creating an API deployment using dialogs in the Console, see Using the Console to Create an API Deployment from Scratch.

To create 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": "<backend-type>",
           "<backend-target>": "<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:

     • 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".
   • <backend-type> specifies the type of the back-end service. Valid values are ORACLE_FUNCTIONS_BACKEND, HTTP_BACKEND, and STOCK_RESPONSE_BACKEND.
   • <backend-target> and <identifier> specify the back-end service. Valid values for <backend-target> and <identifier> depend on the value of <backend-type>, as follows:
     • If you set <backend-type> to ORACLE_FUNCTIONS_BACKEND, then replace <backend-target> with functionId, and replace <identifier> with the OCID of the function. For example, "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab5b...". See Adding a Function in OCI Functions as an API Gateway Back End.
     • If you set <backend-type> to HTTP_BACKEND, then replace <backend-target> with url, and replace <identifier> with the URL of the back-end service. For example, "url": "https://api.weather.gov". See Adding an HTTP or HTTPS URL as an API Gateway Back End.
     • If you set <backend-type> to STOCK_RESPONSE_BACKEND, then replace <backend-target> and <identifier> with appropriate key-value pairs. See Adding Stock Responses as an API Gateway Back End.

   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"
         }
       }
     ]
   }

   For a more complex example that defines multiple back ends, see Example API Deployment Specification with Multiple Back Ends.

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.

To create an API deployment specification based on an API description file you upload for an API resource, see Creating an API Resource with an API Description

The API description file provides some initial values for the API deployment specification, which you can modify and extend when deploying the API resource on an API gateway.

You can create a single API deployment on an API gateway, with an API deployment specification that defines multiple back-end services.

For example, the following API deployment specification defines a simple Hello World serverless function in OCI Functions as one back end, and the National Weather Service API as a second back end.

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/weather",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov"
      }
    }
  ]
}