Google is committed to advancing racial equity for Black communities. See how.

Manage resources

Understand and manage resources, as described in the following sections.

About resources

Many policy types rely on resources. Resources are the files that implement the code or configuration to be executed by a policy when attached to an API proxy. In some cases, as with JavaScript and JavaCallout, a policy simply defines an attachment point in an API proxy where some code should execute. The JavaScript or JavaCallout policy is a pointer to a resource.

The following sample JavaScript sets the HTTP request path to the value of the proxy.basepath variable.

request.headers["RequestPath"] = context.getVariable("proxy.basepath");

Resource types

The following table summarizes the resource types and whether they are supported with Edge or hybrid (Beta):

Resource type Description Edge Hybrid
JAR (java) Java classes in a JAR file referenced by JavaCallout policies. checkmark* checkmark
JavaScript (js) JavaScript referenced by JavaScript policies.   checkmark
JavaScript (jsc) Compiled JavaScript referenced by JavaScript policies. checkmark checkmark
Hosted target (hosted) Node.js files to deploy to Hosted Targets. You can deploy Node.js as Edge backend target applications. checkmark  
Node (node) Node.js files, including the main Node.js file, related source files, and module dependencies. checkmark  
OpenAPI Specification (oas) (Beta) OpenAPI Specification used to validate request and response messages of type JSON or YAML.   checkmark
Property Set (properties) Collection of key/value pairs referenced by hybrid property sets.   checkmark
Python (py) Python scripts referenced by PythonScript policies. Resources must be implemented in "pure Python" (in the Python language only). checkmark* checkmark
WSDL (wsdl) WSDL files referenced by SOAPMessageValidation policies. checkmark checkmark
XSD (xsd) XML schemas referenced by SOAPMessageValidation policies. checkmark checkmark
XSL Transformations (xsl) XSLT transformations referenced by XSLTransform policies. checkmark checkmark

* Available in Edge plans only. See Edge pricing and features.

Where resources are stored

You can store resources to the following locations.

Edge

With Edge, resources can be stored in one of the following three locations:

  • API proxy revision: Resources are available only to the API proxy revisions in which the resources are included. For example, you might include a JavaScript resource with revision 1 of an API proxy, then change the implementation to use a Python script in revision 2 of the proxy. Revision 1 has access to only the JavaScript resource, and revision 2 has access to only the Python resource.
  • Environment: When stored in an environment (for example, test or prod), resources are available to any API proxy deployed in the same environment.
  • Organization: When stored in an organization, resources are available to any API proxy deployed in any environment.

The repositories are available at the following URIs, as described by the Resource files API and later in Manage resources using the API:

  • Organization: /organizations/{org}/resourcefiles
  • Environment: /organizations/{org}/environments/{env}/resourcefiles
  • API Proxy: /organizations/{org}/apis/{api}/revisions/{rev}/resources

The following table shows the methods you can use to create, update, and delete resources for each repository:

Repository Create View Update Delete
API UI API UI API UI API UI
API proxy revision
Environment
Organization

hybrid

With hybrid, resources can be stored in one of the following locations. You can't store resource files in an organization.

  • API proxy revision: Resources are available only to the API proxy revisions in which the resources are included. For example, you might include a JavaScript resource with revision 1 of an API proxy, then change the implementation to use a Python script in revision 2 of the proxy. revision 1 has access to only the JavaScript resource, and revision 2 has access to only the Python resource.
  • Environment: When stored in an environment (for example, test or prod), resources are available to any API proxy deployed in the same environment.

The environment repository is available at the following URI, as described by the List resource files API and later in Manage resources using the API: /organizations/{org}/environments/{env}/resourcefiles

The following table shows the methods you can use to create, update, and delete resources for each repository:

Repository Create View Update Delete
API UI API UI API UI API UI
API proxy revision
Environment

For example, all JavaScript files available to the test environment are stored in the following repository and are available to any API proxy running in the test environment:

/organizations/{org}/environments/test/resourcefiles/jsc

Resource name resolution

Edge and hybrid resolve resource names from the most specific to the most general scope. Resource names are resolved "up the chain", from the API proxy revision level, to the environment level, to the organization level (Edge only).

Let's say that you have populated the same resource in two different repositories — the API proxy revision and the prod environment.

Consider the API proxy that is configured with the following Policy:

<Javascript name='PathSetterPolicy' timeLimit='200'>
    <ResourceURL>jsc://pathSetter.js</ResourceURL>
</Javascript>

The policy reference cannot explicitly resolve to a repository. The first resource at the most granular scope whose name matches the resource name in the policy is resolved.

So, when the API proxy is deployed in the environment prod, the policy will resolve to the environment-scoped pathSetter.js resource.

When deployed in the environment test, the Policy will resolve to the API proxy revision-scoped resource, because the environment-scoped resource is in the prod environment, not the test environment.

Java resource guidelines

You can add compiled Java resources as JAR files using multiple options in curl, such as -T, --data-binary, or -F option (not the -d option). For example:

curl -v -u email -H "Content-Type: application/octet-stream" \
-X POST --data-binary @{jar_file} \
"http://{mgmt_server}:{port}/v1/organizations/{org}/environments/{env}/resourcefiles?name={jar_file}&type=java"
curl -v -u email -H "Content-Type: application/octet-stream" \
-X POST -T "{jar_file}" \
"http://{mgmt_server}:{port}/v1/organizations/{org}/environments/{env}/resourcefiles?name={jar_file}&type=java"
curl -v -u email -H "Content-Type: multipart/form-data" \
-X POST -F "file=@{jar_file}" \
"http://{mgmt_server}:{port}/v1/organizations/{org}/environments/{env}/resourcefiles?name={jar_file}&type=java"

See also:

Node.js resource guidelines

When you reference a Node.js script in an API proxy, you do so with the <ResourceURL> element in the API proxy's TargetEndpoint configuration, as described in Adding Node.js to an existing API proxy. For example:

<ScriptTarget>
    <ResourceURL>node://hello-world.js</ResourceURL>
</ScriptTarget>

That Node.js script and all supporting modules must reside at the API proxy revision scope (in the proxy bundle's /resources/node directory). In the API proxy editor, adding the Node.js resource to the Scripts section accomplishes this. So does using the API (import and update) to store the resource at the API proxy revision scope.

Manage resources using the UI

Manage resources scoped to an API proxy revision using the UI, as described in the following sections.

View resources using the UI

To view the resources scoped to an API proxy revision:

  1. Access the UI, as described below:

    Edge

    Sign in to apigee.com/edge.

    hybrid

    Sign in to apigee.google.com/edge.

  2. Select Develop > API Proxies in the left navigation bar.
  3. Select an API proxy in the list for which you want to create a resource.
    The API proxy editor opens and the Overview tab is displayed, by default.
  4. Click the Develop tab.
  5. Select the revision in the Revision drop-down, if required.

    The resources scoped to the API proxy revision are listed in the Resources section in the Navigator view.

Create a resource using the UI

To create resources scoped to an API proxy revision using the UI:

  1. View the resources scoped to the API proxy revision.
  2. Click + in the Resources section in the Navigator view to open the New Resource dialog.
  3. Enter the following:
    Field Description
    Source Select to create a new file or import a file.
    File Type Select a resource type from the drop-down list.
    File Name Name of the file. The filename extension must be valid for the selected file type.

Update a resource using the UI

Apigee hybrid only:
With Apigee hybrid, you can update a resource scoped to an API proxy revision only if the revision has not been deployed. After an API proxy revision is deployed, it is immutable.

To update a resource scoped to an API proxy revision using the UI:

  1. View the resources scoped to the API proxy revision.
  2. In the Navigator view under Resources, click the resource that you want to update.
    Note: For JAR files, position your cursor over the resource that you want to edit and click .
  3. Update the resource, as required.
    Note: After uploading a new JAR file, click Update.

Delete a resource using the UI

Apigee hybrid only:
With Apigee hybrid, you can delete a resource scoped to an API proxy revision only if the revision has not been deployed. After an API proxy revision is deployed, it is immutable.

To detele a resource scoped to an API proxy revision using the UI:

  1. View the resources scoped to the API proxy revision.
  2. In the Navigator view under Resources, position your cursor over the resource that you want to delete to display the actions menu.
  3. Click .
  4. Click Delete to confirm the action.

Manage resources using the API

Manage resources using the API, as described in the following sections.

Create resources using the API

Create resources that are scoped to an API proxy revision, environment, or organization (Edge only), as described in the following sections.

Create resources scoped to an API proxy revision using the API

Create resources that are scoped to an API proxy revision using the API, as described in the following sections.

Edge

Create a resource scoped to an API proxy revision using the API by issuing a POST request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/apis/{api}/revisions/{rev}/resourcefiles

Pass the following information with your request:

  • Set the name query parameter to the name of the resource
  • Set the type query parameter to the required resource type
  • Pass the contents of the resource file as application/octet-stream or multipart/form-data)

The following example creates a JavaScript file named pathSetter.js for revision 1 of the helloworld API proxy:

curl -X POST https://api.enterprise.apigee.com/v1/organizations/myorg/apis/helloworld/revisions/1/resourcefiles?name=pathSetter.js&type=jsc
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");' \
  -u email:password

The following example shows how to upload the resource as a file from your local machine. It's important to use -F for the binary upload in curl in order for the environment- or organization-scoped JavaScript files to be accessible by the JavaScript policy.

curl -X POST https://api.enterprise.apigee.com/v1/organizations/myorg/apis/helloworld/revisions/1/resourcefiles?name=pathSetter.js&type=jsc
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js \
  -u email:password

The following provides an example of the response from either API call.

{
  "name": "pathSetter.js",
  "type": "jsc"
}

For more information, see:

Alternatively, you can use the Update API proxy revision API, as follows:

  1. Create the resource file.
  2. Add the resource file to an API proxy configuration bundle.
  3. Upload the bundle using one of the following APIs:

Hybrid

To create a resource that is scoped to an API proxy revision using the API:

  1. Create the resource file.
  2. Add the resource file to an API proxy configuration bundle.
  3. Upload the bundle using one of the following APIs:

Create resources scoped to an environment using the API

Create a JavaScript resource that is scoped to to an environment using the API by issuing a POST request to the following resource: /organizations/{org}/environments/{env}/resourcefiles

Pass the following information with your request:

  • Set the name query parameter to the name of the resource
  • Set the type query parameter to the required resource type
  • Pass the contents of the resource file as application/octet-stream or multipart/form-data)

The following example shows how to create a JavaScript resource by passing its contents in the request body.

Edge

curl -X POST https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/resourcefiles?name=pathSetter.js&type=jsc
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");' \
  -u email:password

hybrid

curl -X POST https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles?name=pathSetter.js&type=jsc
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");'

The following example shows how to upload the resource as a file from your local machine. It's important to use -F for the binary upload in curl in order for the environment- or organization-scoped JavaScript files to be accessible by the JavaScript policy.

Edge

curl -X POST https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/resourcefiles?name=pathSetter.js&type=jsc
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js \
  -u email:password

hybrid

curl -X POST https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles?name=pathSetter.js&type=jsc
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js

The following provides an example of the response:

{
  "name" : "pathSetter.js",
  "type" : "jsc"
}

Create resources scoped to the organization using the API (Edge only)

With Edge, To create a resource that is scoped to an organization using the API, issue a POST request to the following resource: https://api.enterprise.apigee.comv1/organizations/{org}/resourcefiles

Pass the following information with your request:

  • Set the name query parameter to the name of the resource
  • Set the type query parameter to type of resource file (see Resource types)
  • Pass the contents of the resource file as application/octet-stream or multipart/form-data)

For more information, see:

View resources using the API

The following sections describe how to view resources using the API.

View all resources using the API

View all resources scoped to an environment using the API, as described in the following sections.

Edge

With Edge, using the API you can view resources scoped to an API proxy revision, environment, or organization.

For example, to view resources for resources scoped to environment using the API, issue a GET request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/environments/{env}/resourcefiles

The following example lists all resources in the test environment:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/my-organization/environments/test/resourcefiles/{type}" \
  -u email:password
  

hybrid

With hybrid, using the API you can view resources scoped to an environment only.

To view all resources in an environment using the API, issue a GET request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

The following example lists all resources in the test environment:

curl -X GET https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles
  -H "Authorization: Bearer $TOKEN"

For more information, see List environment resource files API.

The following provides an example of the response.

{
  "resourceFile": [
{
  "name" : "pathSetter.js",
  "type" : "jsc"
}
  ]
}

View the contents of a resource using the API

View the content of a resource using the API, as described in the following sections.

To view the contents of a resource in an environment using the API, issue a GET request to the following resource: /organizations/{org}/environments/{env}/resourcefiles/{type}/name

The following example displays the contents of the pathSetter.js JavaScript resource file in the test environment:

Edge

With Edge, using the API you can view the contents of resources scoped to an API proxy revision, environment, or organization.

For example, to view the contents of a resource in an environment using the API, issue a GET request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/name

The following example lists the contents of the pathSetter.js JavaScript resource file in the test environment:

curl -X GET https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js" \
  -H "Accept: application/json" \
  -u email

hybrid

With Edge, using the API you can view the contents of resources scoped to an environment only.

To view the contents of a resource in an environment using the API, issue a GET request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/name

The following example lists the contents of the pathSetter.js JavaScript resource file in the test environment:

curl -X GET https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js
  -H "Authorization: Bearer $TOKEN"

The following provides an example of the response:

request.headers["RequestPath"] = context.getVariable("proxy.basepath");

Update resources using the API

Update resources that are scoped to an API proxy revision, environment, or organization (Edge only), as described in the following sections.

Update resources scoped to an API proxy revision using the API

Update resources that are scoped to an API proxy revision using the API, as described in the following sections.

Edge

Update a resource scoped to an API proxy revision using the API by issuing a PUT request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/apis/{api}/revisions/{rev}/resourcefiles/{type}/{name}

Pass the contents of the resource file as application/octet-stream or multipart/form-data)

The following example updates the JavaScript resource named pathSetter for revision 1 of the helloworld API proxy:

curl -X PUT https://api.enterprise.apigee.com/v1/organizations/myorg/apis/helloworld/revisions/1/resourcefiles/jsc/pathSetter.js
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");' \
  -u email:password

The following example shows how to udpate the resource as a file from your local machine. It's important to use -F for the binary upload in curl in order for the environment- or organization-scoped JavaScript files to be accessible by the JavaScript policy.

curl -X PUT https://api.enterprise.apigee.com/v1/organizations/myorg/apis/helloworld/revisions/1/resourcefiles/jsc/pathSetter.js
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js \
  -u email:password

The following provides an example of the response from either API call.

{
  "name": "pathSetter.js",
  "type": "jsc"
}

For more information, see:

Alternatively, you can use the Update API proxy revision API, as follows:

  1. Download the API proxy configuration bundle using the Export API proxy API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  2. Update the resource file in the API proxy configuration bundle.
  3. Upload the bundle using the Update API proxy revision API

Hybrid

To update a resource that is scoped to an API proxy revision using the API:

  1. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  2. Update the resource file in the API proxy configuration bundle.
  3. Upload the API proxy configuration bundle using the Update API proxy revision API.

Update resources scoped to an environment using the API

Update a resource that is scoped to to an environment using the API by issuing a PUT request to the following resource: /organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Pass the contents of the resource file as application/octet-stream or multipart/form-data.

The following example shows how to update a JavaScript resource by passing its contents in the request body.

Edge

curl -X PUT https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");' \
  -u email:password

hybrid

curl -X PUT https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type:application/octet-stream" \
  -d 'request.headers["RequestPath"] = context.getVariable("proxy.basepath");'

The following example shows how to update the resource file using a file from your local machine. It's important to use -F for the binary upload in curl in order for the environment- or organization-scoped JavaScript files to be accessible by the JavaScript policy.

Edge

curl -X PUT https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js \
  -u email:password

hybrid

curl -X PUT https://apigee.googleapis.com/v1/organizations/myorg/environments/test/resourcefiles/jsc/pathSetter.js
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type:multipart/form-data" \
  -F file=@pathSetter.js

The following provides an example of the response:

{
  "name" : "pathSetter.js",
  "type" : "jsc"
}

Update resources scoped to the organization using the API (Edge only)

With Edge, To update a resource that is scoped to an organization using the API, issue a POST request to the following resource: https://api.enterprise.apigee.comv1/organizations/{org}/resourcefiles/{type}/{name}

Pass the contents of the resource file as application/octet-stream or multipart/form-data)

For more information, see:

Delete resources using the API

Delete resource scoped to an API proxy revision, environment, or organization (Edge only), as described in the following sections.

Delete resources scoped to an API proxy revision using the API

Edge

With Edge, to delete a resource scoped to an API proxy revision using the API, issue a DELETE request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/apis/{api}/revisions/{rev}/resourcefiles/{type}/{name}

The following example deletes the pathSetter.js JavaScript resource file from revision 1 of the helloworld API proxy:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/my-organization/apis/helloworld/revisions/1/resourcefiles/jsc/pathSetter.js" \
  -u email:password
  

The following provides an example of the response.

{
  "name" : "pathSetter.js",
  "type" : "jsc"
}

Alternatively, you can use the Update API proxy revision API, as follows:

  1. Download the API proxy configuration bundle using the Export API proxy API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  2. Delete the resource file from the API proxy configuration bundle.
  3. Upload the bundle using the Update API proxy revision API

hybrid

With hybrid, to delete a resource that is scoped to an API proxy using the API:

  1. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  2. Delete the resource file from the API proxy configuration bundle.
  3. Upload the API proxy configuration bundle using the Update API proxy revision API.

Delete a resource scoped to an environment using the API

Delete a resource scoped to an environment using the API, as described in the following sections.

Edge

With Edge, to delete a resource scoped to an environment using the API, issue a DELETE request to the following resource: https://api.enterprise.apigee.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

The following example deletes the pathSetter.js JavaScript resource file from the test environment:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/my-organization/environments/test/resourcefiles/jsc/pathSetter.js" \
  -u email:password
  

hybrid

With hybrid, to delete a resource scoped to an environment using the API, issue a DELETE request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

The following example deletes the pathSetter.js JavaScript resource file from the test environment:

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/jsc/pathSetter.js \
  -H "Authorization: Bearer $TOKEN"
  

For more information, see Delete resource file API.

The following provides an example of the response.

{
  "name" : "pathSetter.js",
  "type" : "jsc"
}

Delete resources scoped to the organization using the API (Edge only)

With Edge, to delete a resource that is scoped to an organization using the API, issue a DELETE request to the following resource: https://api.enterprise.apigee.comv1/organizations/{org}/resourcefiles/{type}/{name}

For more information, see Delete a resource file from an organization.

Access the resource

How you access the resource depends on the resource type. For more information, refer to the relevant policy documentation.

The examples in this section demonstrate how to create and manage a JavaScript resource named pathSetter.js to allow it to be referenced by policies of type JavaScript.

To attach the JavaScript to the Request PostFlow, create a policy called PathSetterPolicy.xml that references the file pathSetter.js:

<Javascript name='PathSetterPolicy' timeLimit='200'>
    <ResourceURL>jsc://pathSetter.js</ResourceURL>
</Javascript>

Then, reference the policy in the Endpoint configuration:

<PostFlow>
  <Request>
    <Step><Name>PathSetterPolicy</Name></Step>
  </Request>
<PostFlow>

For more information, see JavaScript policy.