Apigee Edge to Apigee X migration antipatterns

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

As a current Apigee Edge customer, you might choose to migrate your installation to Apigee X, in order to take advantage of new capabilities, or different regional availability.

This page describes antipatterns in your configuration that you'll need to address before migrating to Apigee X, as well as other changes in behavior that you should be aware of before migrating.

The broader list of Apigee Edge antipatterns describes usage practices that should be avoided in any case. This page describes the specific dis-recommended usage practices that will block a migration. Resolve these now to prevent problems when migrating to Apigee X.

Apps without API products
Summary Requires client-side changes? Resolution

There are apps without API product(s).

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
It is possible to configure an app and credential that is not associated to any API Product. This app effectively has access to all API Products. Each app must be configured to access at least one API Product. There is no way to provide access to all API Products, implicitly. You can configure an app to have access to all API Products, but you need to do so explicitly.
No.

Resolution: Apps without API products

Associate every app credential with at least one API product. For more information on how to do this, see Register apps and manage API keys.

An easy path is to assign each app access to all API Products. This will be the equivalent of what is possible in Apigee Edge. The challenge will be if you want to pursue a "least privilege" approach, then you will need to determine the minimum list of API Products that each app credential must have access to. You can analyze this with Apigee Edge Analytics reports, based on client ID.

Cache without expiry time
Summary Requires client-side changes? Resolution

Cache(s) don't have an expiry time.

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
Supports creation, update, and deletion of cache resource descriptors. Doesn't support creation, update, or deletion of cache resource descriptors.
No

Resolution: Cache without expiry time

Set an expiry time for all caches.

JSONPath filter expressions on non-definite paths
Summary Requires client-side changes? Resolution

For non-definitive paths, querying the result of a filter expressions is not part of JSONPath spec. See https://goessner.net/articles/JsonPath/.

Difference between Apigee Edge and Apigee X:

When navigating this example structure,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

With the expression $..books[?(@.name == 'A')][0],

Apigee Edge Apigee X
Outputs ‘{"name": "A"}’ Outputs []

With the expression $..books[?(@.name == 'A')][0].name,

Apigee Edge Apigee X
Outputs "A" Outputs []
Yes

Resolution: JSONPath filter expressions on non-definite paths

Find and replace affected queries.

JSONPath expressions for indexes that are not present
Summary Requires client-side changes? Resolution

JSONPath expressions with an index that is not present have different behaviors in Apigee X versus Apigee Edge. Apigee X returns an PathNotFoundException error when the path is not found.

Difference between Apigee Edge and Apigee X:

When navigating this example structure,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

With the expression $.books[3],

Apigee Edge Apigee X
Outputs null Outputs PathNotFoundException error
Yes

Resolution: JSONPath expressions for indexes that are not present

Find and replace affected queries.

JSONPath expressions with an array index not returning an array object
Summary Requires client-side changes? Resolution

JSONPath expressions with an array index or slices return an array object in Apigee X.

Difference between Apigee Edge and Apigee X:

When navigating this example structure,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

With the expression $.books,

Apigee Edge Apigee X
Outputs {“name”:”A”, “name”: “B”} Outputs [{“name”:”A”, “name”: “B”}]

With the expression $.books[-1],

Apigee Edge Apigee X
Outputs {“name”: “B”} Outputs [{“name”: “B”}]

With the expression $.books[-2:],

Apigee Edge Apigee X
Outputs {“name”:”A”, “name”: “B”} Outputs [{“name”:”A”, “name”: “B”}]
Yes

Resolution: JSONPath expressions with an array index not returning an array object

Find and replace expressions which might return different results after upgrade.

Keystore name restrictions
Summary Requires client-side changes? Resolution

Apigee X keystore names can only contain letters, numbers, and hyphens. Edge keystore names do not impose these restrictions.

No

Resolution: Keystore name restrictions

Check keystore names and update the names to remove unsupported characters if necessary.

Multiple base paths deployed for an API proxy
Summary Requires client-side changes? Resolution

Multiple revisions of an API proxy are deployed in an environment and each revision has a different base path.

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
Supports deployment of multiple revisions of an API proxy where each revision can have a different base path. Doesn't support deployment of multiple revisions of an API proxy even though the proxy has different base paths.
No

Resolution: Multiple base paths deployed for an API proxy

Update all bundles so that only one revision of a bundle is deployed to an environment, regardless of the basepath.

Non-compliant HTTP messages
Summary Requires client-side changes? Resolution

Clients or the API Proxy send messages (requests or responses) that do not comply with the HTTP standard. For example, invalid Header names, duplications in some restricted headers, and so on.

You cannot migrate to Apigee X if your API execution has one or more of the following errors:

Error Details
INVALID_CHARACTERS_IN_HEADER One or more illegal characters were found in the specified header. Valid header names are composed of English letters, digits, and hyphens.
MISSING_COLON Missing a : (colon) in the header name and header value pair.
MULTIPLE_CONTENT_LENGTH Multiple values were provided for the Content-Length header.
CONTENT_LENGTH_NOT_INTEGER The Content-Length header value is not an integer.
INVALID_UPGRADE The Upgrade header must be used only to enable WebSocket connections but is not.
URL_HEADER_SIZE_TOO_LONG The total size of the request URL and headers exceeds the max allowed size of 15 KB.
BODY_NOT_ALLOWED A message body is not allowed with "GET", "DELETE", "TRACE", "OPTIONS", and "HEAD" methods.
UNSUPPORTED_HTTP_VERSION An HTTP version other than 1.1 is being used for the request and is not supported.
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT A zero ("0") Content-Length header field value was set for a "POST" or "PUT" method.
UNSUPPORTED_RESPONSE_PREFIX An unsupported “X-Apigee-” header prefix was present in the response header.
Yes, possibly.

Resolution: Non-compliant HTTP messages

You must fix any errors in HTTP protocols before migrating to Apigee X. If an error originates from a client application, you must ask the developer of the client app to correct the problem.

OAuth 2.0 token expiration time invalid
Summary Requires client-side changes? Resolution

OAuth 2.0 token expiration limits are outside of the prescribed range.

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
No constraint on the OAuth 2.0 token expiration time is currently enforced but enforcement is planned. See the guidelines in the OAuth section of the Limits page. You must set an access token and refresh token expiry time for OAuth 2.0. The supported ranges are:
  • 180 seconds <= OAuth 2.0 access token expiry time <= 30 days
  • 1 day <= OAuth 2.0 refresh token expiry time <= 2 years
No

Resolution: OAuth 2.0 token expiration time invalid

Use the OAuthV2 policy, and specify the expiry time in <ExpiresIn> and <RefreshTokenExpiresIn>.

Product limits exceeded
Summary Requires client-side changes? Resolution

Configuration of Apigee Edge is not compliant with the defined product limits. Some product limits that are documented but not enforced on Apigee Edgeare enforced on Apigee X.

No

Resolution: Product limits exceeded

Correct any usage that exceeds the product limits before migrating to Apigee X.

ServiceCallout policies with both endpoint and path target connection specifiers
Summary Requires client-side changes? Resolution

In the ServiceCallout policy, the <LocalTargetConnection> element should include either the <APIProxy> and <ProxyEndpoint> elements or the <Path> element, but not both. For more information, see the <LocalTargetConnection> element.

Apigee Edge documents this requirement but does not enforce it. Apigee X stops processing if it encounters a <LocalTargetConnection> with both configurations.

No

Resolution: ServiceCallout policies with both endpoint and path target connection specifiers

Check ServiceCallout policy configurations and eliminate any <LocalTargetConnection> configurations that are not compliant.

Target server name restrictions
Summary Requires client-side changes? Resolution

Apigee X target server names can only contain letters, numbers, hyphens, and periods. Edge target server names do not impose these restrictions.

No

Resolution: Target server name restrictions

Check target server names and update the names to remove unsupported characters if necessary.

Trial certificate in a virtual host
Summary Requires client-side changes? Resolution

One or more Virtual hosts uses the Apigee-provided "free trial" certificate. This causes the virtual host to respond to requests on domains like ORG-ENV.apigee.net.

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
Automatically configures the "default" vhost to support a domain name of the form ORG-ENV.apigee.net. There is a wildcard certificate, known as "the free trial certificate", that allows TLS on these domains. Legacy Apigee domains of the form ORG-ENV.apigee.net are not available in Apigee X. You must configure your own domain name, and provision certificates appropriately.
Yes

Resolution: Trial certificate in a virtual host

You must configure your own domain, and provision certificates appropriately.

Any client application that depends on the legacy domain name of the form ORG-ENV.apigee.net must be modified to call the new domain.

Unresolved DNS
Summary Requires client-side changes? Resolution

The target endpoint(s) have unresolved domain name(s).

Difference between Apigee Edge and Apigee X:

Apigee Edge Apigee X
If DNS resolution fails, Apigee appends .apigee.com to the domain name and the DNS resolves successfully with a 4xx response code. If DNS resolution fails, Apigee does not execute the request and returns a 5xx response code.
No

Resolution: Unresolved DNS

Update the target endpoint with a valid domain name.