Manage API resources with Apigee Spaces

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This topic describes how to create and manage API resources in a Space. You can create API proxies, shared flows, and API products in a Space. Resources created in the Space inherit the same permissions as the Space.

Creating resources in a Space is the same as creating resources under an Apigee organization, except that you can select a Space when you create the resource. You can create API resources from the command line using the Apigee APIs, or by using the Apigee in Cloud console.

This guide outlines the steps required to:

For an overview of Apigee Spaces, see Apigee Spaces.

For more information about the Apigee API resource types, see:

Before you begin

Before you begin creating API resources in Apigee Spaces, make sure you complete the following tasks:

  • Provision your Apigee Subscription or Pay-as-you-go organization. For more information on the steps required to provision Apigee, see Set up Apigee.
  • Create a Space in your Apigee organization. For more information, see Create Apigee Spaces.
  • Assign members to a Space. For more information, see Manage members and roles in a Space.

Required roles and permissions

With the introduction of Apigee Spaces, the way that IAM checks the permissions required to perform some operations on API resources has changed. If the API resource exists in a Space, IAM will check for the appropriate permissions at the Space level, for the Space member performing the operation. For more information, see Apigee Spaces roles and permissions and IAM permission hierarchy for Apigee Spaces.

Assigning roles and permissions to Space members

There are three custom roles available for Space members:

  • apigee.spaceContentEditor: Provides full access to resources that can be associated with a Space. This role should be granted at the Space level.
  • apigee.spaceContentViewer: Provides read-only access to resources that can be associated with a Space. This role should be granted at the Space level.
  • apigee.spaceConsoleUser: Provides the minimum permissions required to manage resources in a Space using the Google Cloud console. This role should be granted at the Google Cloud project level to users with access to resources in that Space.

The custom roles described in this section do not give Space members the ability to deploy or undeploy API proxies or shared flows. If you want to allow a Space member to manage deployments, set an IAM policy at the Apigee environment or Google Cloud project level granting the apigee.environment.admin role to the Space member.

You can assign a role or roles to a Space member using one of the following methods:

  • Add the apigee.spaceContentEditor role to the Space using the API and add the apigee.environmentAdmin role to the target environment using the API.
  • Add the roles to the project using the IAM user interface.

To check for the roles at the Google Cloud project level:

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

To grant the roles

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.
  3. Click Grant access.

  4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

  5. In the Select a role list, select a role.
  6. To grant additional roles, click Add another role and add each additional role.
  7. Click Save.

To check for the IAM policies applied at the Space level, see Manage members and roles in a Space.

Manage API proxies in a Space

Apigee organization members assigned to a Space can create API proxies as Space resources. Members assigned only to other Spaces will not be able to access or manage these proxies.

Create an API proxy as a Space resource using the Apigee in Cloud console or the API, as described in the following sections.

Apigee in Cloud console

To create an API proxy as a Space resource using the Apigee in Cloud console:

  1. Follow the steps outlined in Creating an API proxy.
  2. In Step 5, you will see an additional field under Proxy details where you can select a Space for the API proxy. Select a Space from the list box. If you do not wish to assign the API proxy to a space, you can skip this field.
  3. Click Next to proceed to the optional deployment step of proxy creation or click Create to create the proxy without deploying it.

Apigee API

To create an API proxy as a Space resource using the Apigee APIs, use the following command: 

curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/apis?name=PROXY_NAME&space=SPACE_NAME&action=import" \
    -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-type: multipart/form-data" \
    -F "file=@PROXY_BUNDLE"

Where:

  • ORG_NAME is the name of your Apigee organization.
  • PROXY_NAME is the name of the API proxy you are creating. The name must be globally unique and not just unique within the Space.
  • SPACE_NAME is the name of the Space where you are creating the API proxy.
  • PROXY_BUNDLE is the name of the API proxy bundle file.

For example, with the following command, a red team member creates an API proxy named proxy-1 as a red Space resource in the acme organization using the proxy-bundle.zip file: 

curl "https://apigee.googleapis.com/v1/organizations/acme/apis?name=proxy-1&space=red&action=import" \
    -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-type: multipart/form-data \
    -F "file=@proxy-bundle.zip"

The following example shows the response to the command: 

{
  "basepaths": ["/proxy-1"],
  "revision": 1,
  "apiProxyId": "proxy-1",
  "resourceName": "organizations/acme/apis/proxy-1/revisions/1",
  "space": "red",
  "createTime": ...,
  "updateTime": ...
}

Manage shared flows as Space resources

Members assigned to a Space can also create shared flows as Space resources. Members of other Spaces will not be able to access or manage these shared flows.

Create a shared flow as a Space resource using the Apigee in Cloud console or the API, as described in the following sections.

Apigee in Cloud console

To create a shared flow as a Space resource using the Apigee in Cloud console:
  1. follow the steps outlined in Creating a shared flow in the Apigee UI to create a new shared flow from scratch or upload an existing flow bundle.
  2. In Step 4, you will see an additional field in the Create a shared flow dialog where you can select a Space for the API proxy. Select a Space from the list box. If you do not wish to assign the API proxy to a space, you can skip this field.
  3. Click Create to create the shared flow.

Apigee API

To create a shared flow as a Space resource using the Apigee APIs, use the following command: 

curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sharedflows?name=FLOW_NAME&space=SPACE_NAME&action=import" \
    -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-type: multipart/form-data" \
    -F "file=@SHARED_FLOW_BUNDLE"

Where:

  • ORG_NAME is the name of your Apigee organization.
  • FLOW_NAME is the name of the shared flow you are creating. The name must be globally unique and not just unique within the Space.
  • SPACE_NAME is the name of the Space where you are creating the shared flow.
  • SHARED_FLOW_BUNDLE is the name of the shared flow bundle file.

For example, with the following command, a red team member creates a shared flow named flow-1 associated with the red Space in the acme organization: 

curl "https://apigee.googleapis.com/v1/organizations/acme/sharedflows?name=flow-1&space=red&action=import" \
    -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-type: multipart/form-data" \
    -F "file=@sharedflow-bundle.zip"

The following example shows the response to the command: 

{
  "name": "organizations/acme/sharedflows/flow-1",
  "revision": 1,
  "sharedFlowId": "flow-1",
  "space": "red",
  "createTime": ...,
  "updateTime": ...
}

Manage an API product as a Space resource

Members assigned to a Space can create an API product to bundle their API proxies. When creating API products, Space members can select any API proxies accessible to them, including proxies created directly under the organization and API proxies created as resources in Spaces where they have membership. Members of other Spaces will not be able to access or manage these API products.

Create an API product as a Space resource using the Apigee in Cloud console or the API, as described in the following sections.

Apigee in Cloud console

To create an API product as a Space resource using the Apigee in Cloud console:

  1. Follow the steps in Creating an API product.
  2. In Step 4, you will see an additional field in the Product details page where you can select a Space for the API product. Select a Space from the list box. If you do not wish to assign the API product to a space, you can skip this field.
  3. Complete the remaining configuration information, then click Save.

Apigee API

To create an API product as a Space resource using the API, send a request to the apiproducts/create endpoint and add the space property.

For example, the following command would create an API product named product-1 in the acme organization and associated with the red Space: 

curl -X POST "https://apigee.googleapis.com/v1/organizations/acme/apiproducts" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-type: application/json" -d \
      `{
        "name": "product-1",
        "displayName": "product-1",
        "approvalType": "auto",
        "attributes": [
          {
            "name": "access",
            "value": "internal"
          }
        ],
        "environments": [
          "test"
        ],
        "operationGroup": {
          "operationConfigs": [
            {
              "apiSource": "proxy-1",
              "operations": [
                {
                  "resource": "/",
                  "methods": [
                    "GET"
                  ]
                }
              ]
            }
          ],
          "operationConfigType": "proxy"
        },
        "space": "red"
      }'

The following example shows the response to the command: 

{
  "name": "product-1",
  "displayName": "product-1",
  "approvalType": "auto",
    "attributes": [
      {
        "name": "access",
        "value": "internal"
      }
    ],
    "environments": [
    "test"
  ],
  "createdAt": "1741977778448",
  "lastModifiedAt": "1741977778448",
  "operationGroup": {
    "operationConfigs": [
      {
        "apiSource": "proxy-1",
        "operations": [
          {
            "resource": "/",
            "methods": [
              "GET"
            ]
          }
        ]
      }
    ],
    "operationConfigType": "proxy"
  },
  "space": "red"
}

List all API resources associated with a space

For all list operations, including ListApiProxies, ListSharedFlows, and ListApiProducts, you can specify a Space name to list all the resources associated with that Space. If you do not specify a Space name, the list operation will return all resources in the organization that you have permission to access, whether or not those resources are associated with a Space.

It is important to note that, when using the Apigee Spaces feature, the results of list operations for API resources assigned to a Space will be limited to results for the Spaces the principal can access. For example, if acme-team@acme.com is given the apigee.spaceContentEditor role for the red Space, team acme-team members using the list operation will only see API proxies that are associated with the red space and not all API #proxies in the organization.

To perform this task, you must have the apigee.apiResources.list permission. This permission is included in the Apigee > Apigee Organization Admin role.

List API resources associated with a specific Space

List all API resources associated with a specific Space in the Apigee in Cloud console, or using the API, as described in the following sections.

Apigee in Cloud console

To list all API resources associated with a specific Space in the Apigee in Cloud console, open the overview page for the relevant resource type (API proxies, shared flows, or API products). In the Filter box, select the Space option from the list, then enter the name of the Space. The list of resources assigned to that space displays. Note that only resources associated with a Space where the user is a member are displayed.

Apigee API

To list all API resources associated with a specified Space, use the following command: 

curl -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/RESOURCE_TYPE?space=SPACE_NAME"

Where:

  • ORG_NAME is the name of your Apigee organization.
  • RESOURCE_TYPE is the type of the resource you are listing. Valid values include:
    • apis
    • sharedFlows
    • apiProducts
  • SPACE_NAME is the name of the Space where you are listing the resource.

For example, with the following command, a red team member lists all API proxies associated with the red Space in the acme organization: 

curl -H  "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations/acme/apis?space=red"

The following example shows the response to the command: 

{
  "proxies": [
    {
      "basepaths": "/proxy-1",
      "revision": "1",
      "apiProxyId": "proxy-1",
      "resourceName": "organizations/acme/apis/proxy-1/revisions/1",
      "space": "red",
      "createTime": ...,
      ....
    }
  ]
}

List API resources without specifying a Space

List all API resources without specifying a Space in Apigee in Cloud console, or using the API, as described in the following sections.

Apigee in Cloud console

To view a list of all API resources of a given type in Apigee in Cloud console, regardless of Space association, open the overview page for the relevant resource type (API proxies, shared flows, or API products). A list of all available resources displays. Note that only resources that the user has permission to view are displayed. This includes resources associated with a Space or Spaces where the user is a member, or resources not associated with a Space.

Apigee API

You can also list API resources without specifying a Space using the following command: 

curl -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/RESOURCE_TYPE"

Where:

  • ORG_NAME is the name of your Apigee organization.
  • RESOURCE_TYPE is the type of the resource you are listing. Valid values include:
    • apis
    • sharedFlows
    • apiProducts

For example, a user with Organization Admin access to all organization resources can use the following command to list all API proxies in the acme organization: 

curl -H  "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations/acme/apis"

If the acme organization has three proxies, the command will return details about all three proxies. For example: 

{
  "proxies": [
    {
      "basepaths": "/proxy-1",
      "revision": "1",
      "apiProxyId": "proxy-1",
      "resourceName": "organizations/acme/apis/proxy-1/revisions/1",
      "space": "red",
      "createTime": ...,
      ....
    },
    {
      "basepaths": "/proxy-2",
      "revision": "1",
      "apiProxyId": "proxy-2",
      "resourceName": "organizations/acme/apis/proxy-2/revisions/1",
      "space": "blue",
      "createTime": ...,
      ....
    },
    {
      "basepaths": "/proxy-3",
      "revision": "1",
      "apiProxyId": "proxy-3",
      "resourceName": "organizations/acme/apis/proxy-3/revisions/1",
      "space": "green",
      "createTime": ...,
      ....
    }
  ]
}

If another user with only apiAdmin access to resources in space red uses the same command, the command will only return details about proxy-1. The response would look like this: 

{
  "proxies": [
    {
      "basepaths": "/proxy-1",
      "revision": "1",
      "apiProxyId": "proxy-1",
      "resourceName": "organizations/acme/apis/proxy-1/revisions/1",
      "space": "red",
      "createTime": ...,
      ....
    }
  ]
}

What's next