Retrieve entity profiles using AccessEntity

Was this helpful?

The API Platform stores profile data for a range for "entities", such as developers, apps, and API products. The AccessEntity policy enables developers to retrieve profiles during API proxy message processing. The AccessEntity policy functions as a policy-based runtime database lookup. The profile information can be used to enable conditional endpoint routing, flow execution, policy enforcement, and so on.

For example, you could use the AccessEntity policy to get the profile for an app, and then extract a custom field (such as a department name) from the app profile. Using the department name as a variable, you could route the request to a specific backend service, or you could forward the department name to Analytics to enable data accounting.

When a policy of type AccessEntity is enforced:

  1. The policy sets an entity as an XML-formatted flow variable. The variable that is set is usually consumed by an ExtractVariable or AssignMessage policy, as illustrated in Extract message content using ExtractVariables and Generate or modify messages using AssignMessage .
  2. XPath is used to parse the desired properties from the profile. For examples see Retrieving entity profilres using the Platform API.
  3. If the specified entity is not found, the policy returns ResourceNotFoundException.

AccessEntity is used to access profiles for the following entities:

  • App
  • API product
  • Company
  • Company developer
  • Consumer key
  • Developer

The basic of structure of an AccessEntity policy is:

<AccessEntity name="{policy_name}">
    <EntityType  value="{entity_type}"/>
    <EntityIdentifier ref="{entity_identifier}" type="identifer_type"/> 
    <SecondaryIdentifier* ref="{secondary_identifier}" type="identifer_type"/>
</AccessEntity>
Back to top

Configuring an AccessEntity policy

AccessEntity policies expose the following configuration settings:

Name Description Default Required?
AccessEntity A policy used to retrieve entity profiles from the API Platform data store.
Name The unique name of the policy. N/A Yes
EntityType The name of the type of entity to be retrieved. For a reference of entity types, see the EntityType specification.  N/A Yes
EntityIdentifier

The value that identifies the specific entity whose profile should be retrieved.

The ref attribute identifies the variable that provides the source of the identifier, for example, request.queryparameter.apikey

.

The type identifies the EntityType populated by the referenced variable, such as consumerkey.

 N/A No
SecondaryIdentifier

Use when EntityIdentifier is not guaranteed unique, as with appname.

Also use to filter queries that return multiple results.

The ref attribute identifies the variable that provides the source of the identifier, for example, request.queryparameter.apikey.

The type identifies the entity type populated by the referenced variable, such as consumerkey. The use of multiple SecondaryIdentifier elements is not supported. This element is optional to support backward-compatibility with existing deployments.

 N/A No

Where multiple matches exist for a given EntityIdentifier and SupportingIdentifier combination, the first match will be populated in the Flow. An example of such a potential conflict is retrieving an apiproduct based on appid. For example:

  • EntityType is set to apiproduct
  • EntityIdentifier is set to appid

Since an app can be associated with multiple API products, only the first matched API product will be available in the Flow.

To resolve such potential conflicts, you can use a SecondaryIdentifier. For example, during an OAuth 2.0 exchange, appname and developerid variables are populated by default in the Flow. Those two variables can therefore be used by an AccessEntity policy to get profile details on the requesting app. To prevent conflicts, set the EntityIdentifier to appname and developerid as the SecondaryIdentifier.

Back to top

AccessEntity variables

When the entity profile specified in the AccessEntity policy is retrieved, the XML-formatted profile object is added to the message context as a variable. It can be access like any other variable, with reference to the variable name. The user-provided name of the AccessEntity policy is set as the variable prefix of the variable name.

For example, if an AccessEntity policy with name of GetDeveloper is executed, then the XML-formatted profile is stored in the variable named AccessEntity.GetDeveloper. The XML-formatted profile can then be parsed using an XPath defined in an ExtractVariables policy that specifies AccessEntity.GetDeveloper as its source.

Back to top

EntityType specification

EntityType EntityIdentifiers SecondaryIdentifiers
apiproduct
  • apiproductname
  • appname
  • appid
  • consumerkey
  • developeremail
  • developerid
  • companyname
  • apiresource

The SecondaryIdentifiers developeremail, developerid and companyname are used only when the EntityIdentifier is appname.

TheSecondaryIdentifier apiresource is used only when the EntityIdentifier is appname, appid, and consumerkey.
app
  • appname
  • appid
  • consumerkey
  • developeremail
  • developerid
  • companyname

Used only when identifier is appname, because the value of appname is not guaranteed to be unique across an organization.
company
  • companyname
  • appid
  • consumerkey
 None
companydeveloper
  • companyname
 None
consumerkey
  • consumerkey
 None
developer
  • developeremail
  • developerid
  • appid
  • consumerkey
 None
Back to top

Example: AccessEntity policy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity enabled="true" continueOnError="false" async="false" name="name_of_the_policy">
    <FaultRules/>
    <Properties/>
    <EntityIdentifier ref="reference_to_entity_identified"/>
    <EntityType  value="type_of_entity"/>
</AccessEntity>

Back to top

Configuring ExtractVariables to use AccessEntity lookup

When an AccessEntity policy executes, the result is a Flow variable populated with an XML-formatted profile object. The XML-formatted profile object can be used as a source of data for a Flow by configuring an ExtractVariables policy to parse the profile.

In the following example, an ExtractVariables policy is used to parse a developer profile retrieved by AccessEntity to obtain the value of a custom attribute. The source is set to point to the variable where the developer profile is stored by the AccessEntity policy: AccessEntity.{policy_name}. The profile can be parsed using XPath, just as any other XML document. Sample profiles for entities managed by the API Platform are provided below.

<ExtractVariables name="GetDeveloperAttribute">
  <Source>AccessEntity.GetDeveloper</Source> 
  <VariablePrefix>developer_attribute</VariablePrefix>
  <XMLPayload>
    <Variable name="developer_attribute" type="string">
      <XPath>/Developer/Attributes/Name</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>
Back to top

Retrieving entity profiles using the Platform API

When configuring an AccessEntity policy, it can be useful to retrieve sample entity profiles to assist in selection of appropriate identifiers. For details, refer to the API resources reference

For example:

Apps

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

Or:

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u myname:mypass

Sample profile:

<ApiProduct name="FreeProduct">
    <ApiResources>
        <ApiResource>/**</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes/>
    <CreatedAt>1362502867450</CreatedAt>
    <CreatedBy>ambrown2000@yahoo.com</CreatedBy>
    <Description>You get what you pay for!</Description>
    <DisplayName>Free API bundle</DisplayName>
    <Environments>
        <Environment>test</Environment>
        <Environment>prod</Environment>
    </Environments>
    <LastModifiedAt>1362502867450</LastModifiedAt>
    <LastModifiedBy>ambrown2000@yahoo.com</LastModifiedBy>
    <Proxies>
        <Proxy>apikey</Proxy>
        <Proxy>oauth-authcode</Proxy>
        <Proxy>oauth-client-credentials</Proxy>
        <Proxy>oauth-verify-accesstoken</Proxy>
        <Proxy>oauth-login-app</Proxy>
    </Proxies>
    <Quota>1</Quota>
    <QuotaInterval>1</QuotaInterval>
    <QuotaTimeUnit>minute</QuotaTimeUnit>
    <Scopes>
        <Scope>READ</Scope>
    </Scopes>
</ApiProduct>

API product

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u myname:mypass

Sample XPath, retrieves the second API resource (URI) from the API product named weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>

Company

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u myname:mypass

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>

Company developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u myname:mypass

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

Consumer key

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u myname:mypass

Sample XPath:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>

Developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u myname:mypass

Sample XPath:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
/Developer/Email/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>
Back to top