Create property sets

In Apigee hybrid, a property set is a custom collection of key/value pairs that store data. API proxies can retrieve this data when they execute.

About property sets

Property sets, like other runtime data, are deployed to the cluster by hybrid. The general process is as follows:

  1. You create a property set in the Edge UI or with the management API.
  2. The hybrid management plane validates the property set; if valid, the properties are stored in the management plane.
  3. The Synchronizer retrieves the property set data and stores it locally on the runtime plane.
  4. The Message Processor loads the downloaded property set and makes it available to executing proxies.

Why use property sets?

Typically, you use property sets to store non-expiring data that shouldn't be hard-coded in your API proxy logic. You can access property set data anywhere in a proxy where you can access flow variables.

A common use case for property sets is to provide values that are associated with one environment or another. For example, you can create an environment-scoped property set with values that are specific to proxies running in your test environment, and another set for your production environment.

For example:

  • prod-env.properties contains the property log-level=error
  • test-env.properties contains the property log-level=debug

Similarly, you might store environment-specific routing information:

  • test-env.properties contains the property db-url=mydomain.test.datasource.com
  • prod-env.properties contains the property db-url=mydomain.prod.datasource.com

Property sets vs. KVMs

In hybrid, you can use property sets for some of the same use cases as the key value map (KVM) feature.

Key differences between property sets and KVMs include:

  • You create property sets on the management plane using a management API or the UI. Data is synchronized with the runtime plane.
  • You cannot create KVMs on the management plane.
  • You cannot encrypt property set data.
  • You can only create and access KVMs using the KVM policies (at proxy runtime).

Property set scopes

You can scope a property set to an organization, environment, or API proxy:

  • Organization-scoped property sets: Properties are available to all environments and all API proxies within that organization.
  • Environment-scoped property sets: Properties are available to all proxies within that environment. Proxies within other environments cannot access that property set.
  • Proxy-scoped property sets: Properties are available only to that API proxy. No other API proxy, even those within the same environment or organization, can access that property set.

You specify the scope when you create a property set, but which scope you can specify depends on whether you create a property set in the UI or with the management API .

The following table shows the different scopes and which method(s) you can use to create, edit, and delete property sets for each scope:

Scope Create Delete Update/Replace
API UI API UI API UI
API Proxy scope
Environment scope
Organization scope

Property set files

Property sets are a resource type in Edge. You typically store the values of property sets in a property set file that contains name/value pairs.

Property set files support the same syntax as Java properties files; for example, they can contain Unicode values and can use # or ! characters as comment markers.

The following example shows a simple property set file that defines several properties:

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

After you create a property set file, you upload it to your hybrid deployment using either the UI or the management API.

Create property sets

You can create property sets in one of the following ways:

  • UI: You can define the properties directly in the UI or in a property set file that you upload in the UI.
  • Management API: You must define a property set file that you then upload with the management API.

You cannot create or manage property sets using policies.

Create property sets with the UI

This section describes how to create property sets using the UI.

To create a new proxy-scoped property set in the UI:

  1. (Optional) Define a property set file in a text editor.
  2. Open the Edge Management UI in a browser.
  3. Select Develop > API Proxies > proxy.
  4. Click the Develop tab.
  5. In the Navigator, click the + next to Resources:

    The New Resources dialog appears:

  6. From the File Type drop-down list, select "Property Set".
  7. If you have a property set file to upload:
    1. Select the Import File radio button.
    2. Click the Choose file button, navigate to the file on your local machine, and select it.
  8. In the File Name field, enter a property set name. The name must end with ".properties". For example, if you want to name your property set "danger", enter "danger.properties" in the File Name field.
  9. Click the Add button. The UI validates and then stores your property set. When the Synchronizer discovers the new set, it downloads it, and propagates it to the cluster so that its values are available to all API proxies.
  10. If you did not upload a property set file, add name=value pairs in the resource editor as described in Update property sets.

Create property sets with the management API

To create property sets with the management API, you define a property set file and then upload it to your hybrid organization using a POST request.

Use the following APIs to create property sets with the management API:

# Create an organization-scoped property set:
curl -X POST -H "Content-type:multipart/form-data" -u username -F file=@filename
  https://api.enterprise.apigee.com/v1/organizations/your_org/resourcefiles?name=property_set_name&type=properties

# Create an environment-scoped property set:
curl -X POST -H "Content-type:multipart/form-data" -u username -F file=@filename \
  https://api.enterprise.apigee.com/v1/organizations/your_org/environment/your_env/resourcefiles?name=property_set_name&type=properties

For example:

# Example of creating an organization-scoped property set:
curl -v -X POST -H "Content-type:multipart/form-data" \
  -u user@example.com -F file=@/Users/myhome/myprops.properties \
  'https://api.enterprise.apigee.com/v1/organizations/MyOrganization/resourcefiles?name=MyPropSet&type=properties'

# Example of creating an environment-scoped property set:
curl -v -X POST -H "Content-type:multipart/form-data" \
  -u user@example.com -F file=@/Users/myhome/myprops.properties \
  'https://api.enterprise.apigee.com/v1/organizations/MyOrganization/environment/test/resourcefiles?name=MyPropSet&type=properties'

Property sets that you created and uploaded with the management API are not visible in the UI. (The UI can only access proxy-scoped property sets, which the management API cannot create.)

Delete property sets

You can delete a property set using the management API or the UI.

To delete a property set with the management API, send a DELETE request with the following syntax:

curl -X DELETE -H "Content-type:multipart/form-data" -u username \
  https://api.enterprise.apigee.com/v1/organizations/your_org/resourcefiles/properties/property_set_name

For example:

curl -X DELETE -H "Content-type:multipart/form-data" -u user@example.com \
  https://api.enterprise.apigee.com/v1/organizations/MyOrganization/resourcefiles/properties/MyPropSet

To delete a property set with the UI:

  1. Open the Edge Management UI in a browser.
  2. Select Develop > API Proxies > proxy.
  3. Click the Develop tab. A list of existing property sets is shown in the Navigator.
  4. In the Navigator, hover over the property set in the list under Resources. An X appears:

  5. Click the X next to the property set you want to delete. The UI prompts you to confirm the deletion:

  6. Click the Delete button.

Update property sets

This section describes how to update property sets.

  • UI: You can update individual property values or the entire property set.
  • Management API: You can replace an entire property set with a new property set file.

Update properties with the UI

You can update values of individual properties in a proxy-scoped property set by using the Edge UI. You cannot update individual properties by using the management API.

To update the value of a property by using the UI:

  1. Open the Edge Management UI in a browser.
  2. Select Develop > API Proxies > proxy.
  3. Click the Develop tab. A list of existing property sets is shown in the Navigator.
  4. Click the property set you want to edit. The name/value pairs in the property set appear in the Code Editor:

  5. In the Code Editor, make your changes to the property set. You can add and remove properties or change the values of properties. You can replace the entire contents of the property set by pasting over the existing values.
  6. To save your changes, click Save > Save as new revision.

Replace a property set

You can replace a property set with a new property set file by using the management API.

The APIs for replacing a property set are the same as the APIs for creating a new property set, except that you use the HTTP PUT verb.

Use the following APIs to replace a property set scoped to an organization or an environment:

# Replace an organization-scoped property set:
curl -X PUT -H "Content-type:multipart/form-data" -u username -F file=@filename \
  https://api.enterprise.apigee.com/v1/organizations/your_org/resourcefiles?name=property_set_name&type=properties

# Replace an environment-scoped property set:
curl -X PUT -H "Content-type:multipart/form-data" -u username -F file=@filename \
  https://api.enterprise.apigee.com/v1/organizations/your_org/environment/your_envresourcefiles?name=property_set_name&type=properties

For example:

# Example that updates an organization-scoped property set:
curl -v -X PUT -H "Content-type:multipart/form-data" -u user@example.com -F file=@/Users/myhome/myprops.properties \
  'https://api.enterprise.apigee.com/v1/organizations/MyOrganization/resourcefiles?name=MyPropSet&type=properties'

# Example that updates an environment-scoped property set:
curl -v -X PUT -H "Content-type:multipart/form-data" -u user@example.com -F file=@/Users/myhome/myprops.properties \
  'https://api.enterprise.apigee.com/v1/organizations/MyOrganization/environments/prod/resourcefiles?name=MyPropSet&type=properties'

Access property set values

You can access property set values anywhere in a proxy where you can access flow variables: in policies, flows, JavaScript code, and so on.

To access values in a property set, use the following syntax:

propertyset.[property_set_name].[property_name]

Where:

  • property_set_name is the filename that you uploaded (if you used the UI) or the value of the name query parameter (if you used the management API).
  • property_name is the name of the property. For example, if your property set contains foo=bar, foo is the name of the property and bar is the value.

For example, in a JavaScript policy, use the getVariable() method to get a value from a property set:

context.getVariable('propertyset.property_set_name.property_name);

The following example gets the value of the foo property in the property set named "MyPropSet":

context.getVariable('propertyset.MyPropSet.foo);

If you created the property set with the UI, be sure to include the ".properties" part of the name. For example:

context.getVariable('propertyset.danger.properties.foo);

You can also use the ExtractVariables policy to get the value of a property from a property set, as the following example shows:

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <Variable name="myVar">
      <Pattern>{propertyset.MyPropSet.foo}</Pattern>
   </Variable>
   <VariablePrefix>foobar</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Property set limits

Apigee hybrid imposes the following limits on property sets. These limits are validated by the management plane when the property set is created:

Threshold Limit
Maximum number of properties defined in a property set 100
Maximum size of each property name in a property set 100 Bytes
Maximum size of each value in a property set 1024 Bytes
Maximum size of a property set file (100 + 1024) * 100 = ~110KB
Maximum number of property sets for each organization, environment, and API proxy 10 sets
Maximum memory consumed Approximately 3 MB

In addition to the limits described above, property set files must use the same syntax as Java properties files.