You're viewing Apigee Edge documentation.
View Apigee X documentation.
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:
|
No. |
Resolution: Apps without API productsAssociate 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:
|
No |
Resolution: Cache without expiry timeSet an expiry time for all caches. |
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
With the expression
|
Yes |
Resolution: JSONPath filter expressions on non-definite pathsFind 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 Difference between Apigee Edge and Apigee X: When navigating this example structure, { "books": [ { "name": "A", }, { "name": "B", } ] } With the expression
|
Yes |
Resolution: JSONPath expressions for indexes that are not presentFind 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
With the expression
With the expression
|
Yes |
Resolution: JSONPath expressions with an array index not returning an array objectFind and replace expressions which might return different results after upgrade. |
Keystore name restrictions
Apigee X keystore names can only contain letters, numbers, and hyphens. Edge keystore names do not impose these restrictions.
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
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. |
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
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:
- INVALID_CHARACTERS_IN_HEADER
- MISSING_COLON
- MULTIPLE_CONTENT_LENGTH
- CONTENT_LENGTH_NOT_INTEGER
- INVALID_UPGRADE
- URL_HEADER_SIZE_TOO_LONG
- BODY_NOT_ALLOWED
- UNSUPPORTED_HTTP_VERSION
- ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT
- UNSUPPORTED_RESPONSE_PREFIX
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
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:
|
Resolution: OAuth 2.0 token expiration time invalid
Use the OAuthV2 policy, and specify the expiry time in
<ExpiresIn>
and
<RefreshTokenExpiresIn>
.
Product limits exceeded
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.
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
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.
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
Apigee X target server names can only contain letters, numbers, hyphens, and periods. Edge target server names do not impose these restrictions.
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
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.
|
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
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.
|
Resolution: Unresolved DNS
Update the target endpoint with a valid domain name.