API Design, Products and Developer Apps in Apigee

1. Wildcards must match whole path segments. In a product, /* covers one level under the base path and /** covers every deeper level. An operation such as /orders/* means "any single order", and the design must put resource identifiers in their own segments for that to work.
2. The error contract is a gateway job too. Failures raised by the proxy, such as an invalid key or an exceeded quota, are generated by Apigee, not your backend. A RaiseFault policy can return your standard shape:

<RaiseFault name="RF-InvalidRequest">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="application/json">{
  "error": { "code": "invalid_request", "message": "Pass a status of open, shipped or cancelled." }
}</Payload>
      <StatusCode>400</StatusCode>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

3. Idempotency is a backend promise. A gateway that retries a non-idempotent POST can charge a card twice. Decide where retries live (usually the client) and make POST /orders safe with a key stored by the backend.

Versioning and how base paths implement it

An API version is a contract with consumers. It is not the same as a proxy revision, which is a numbered snapshot of one proxy's configuration (a change you want to deploy is saved as a new revision). Revisions are how you ship fixes to a version. Versions are how you ship breaking changes.

Path versioning fits Apigee well because of how routing works. A client call is a hostname, then a base path, then a resource path. The hostname comes from an environment group, and the base path selects the proxy. Base paths must be unique (the environments page states the rule per environment group, the configuration reference per environment), so two proxies cannot share one on the same hostname. That gives a simple pattern: deploy one proxy per major version, each with its own base path.

Because each version is its own proxy, you can retire v1 without touching v2, give each version its own product, and run different policy sets per version. The cost is some duplication; shared flows (see the proxies lesson) keep the common parts in one place.

Which strategy to use, and when to cut a new version, is a decision you can run as a flowchart.

How to read it: most changes are additive and need no new version. A new major version is the expensive path, and the last step (watching which apps still call v1) is what makes retirement safe.

API products: what you actually sell and share

An API product is a named bundle of operations plus the rules that apply to them. Each operation names one proxy and a resource path, and can limit HTTP methods and carry its own quota. Around the operations a product carries:

• Environments it is valid in. If the list is empty, all environments are allowed.
• Approval type: keys are approved automatically, or each request waits for manual approval.
• Quota: a limit (requests per interval) that applies to apps holding the product. A quota set on an operation takes precedence over the product-level quota.
• OAuth scopes that apps may request.
• Access level: public, private or internal only. Public products can be added to a developer portal. Apigee states there is no functional difference between private and internal only: the choice describes the intended audience.
• Custom attributes, up to 18, which a proxy can read at runtime.

Why products rather than proxies? A proxy answers "how does this API behave". A product answers "who may use which part of it, and how much". One proxy can sit behind many products: a read-only product, a read-write product, a high-quota premium product. Selling or sharing the product leaves the proxy untouched. Apigee's own examples include a free read-only tier and a premium tier with read and write access, built from the same resources.

Here is the REST shape of a product with two operations, per the documented ApiProduct fields. Quota numbers are illustrative (assumed).

{
  "name": "partner-orders-read",
  "displayName": "Partner Orders (read only)",
  "approvalType": "auto",
  "environments": ["prod"],
  "operationGroup": {
    "operationConfigs": [
      {
        "apiSource": "orders-v1",
        "operations": [{ "resource": "/orders", "methods": ["GET"] }],
        "quota": { "limit": "1000", "interval": "1", "timeUnit": "hour" }
      },
      {
        "apiSource": "orders-v1",
        "operations": [{ "resource": "/orders/*", "methods": ["GET"] }],
        "quota": { "limit": "5000", "interval": "1", "timeUnit": "hour" }
      }
    ]
  }
}

Developers, apps and credentials

A developer is a registered identity, normally with an email address. A developer app belongs to a developer, is associated with at least one product, and receives credentials. The documented behaviour worth remembering:

• Each app can hold multiple credentials, each with its own expiry date or none. That is how you rotate keys: generate a new credential, let the client switch, then revoke the old one. Old keys keep working until they expire or are revoked.
• Each credential is linked to one or more products. The pair of credential and product has a status of approved or revoked. Manually approved products start as pending.
• An app name cannot be changed after creation, and the optional callback URL is used by authorisation-code OAuth flows.
• Apigee caches developer, app and token data for at least 180 seconds, so a revocation can take a few minutes to reach every message processor.

The proxy has to check the credential. The policy is a few lines:

<VerifyAPIKey name="VAK-VerifyKey">
  <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Attach it to the proxy's PreFlow request. On success, Apigee sets flow variables named after the policy, for example verifyapikey.VAK-VerifyKey.app.name and verifyapikey.VAK-VerifyKey.apiproduct.name, which later policies and analytics can use. A key that does not match gives oauth.v2.InvalidApiKey, a missing key location gives oauth.v2.FailedToResolveAPIKey, and a valid key whose product does not cover the proxy and path gives oauth.v2.InvalidApiKeyForGivenResource. All three are HTTP 401. Match on the fault code, not the message text, which can change.

The onboarding sequence

This is what happens from sign-up to the first successful call, with a portal in front.

How to read it: the portal and the Apigee control plane hold registration data. The runtime only verifies and enforces. If the product is set to manual approval, the sequence pauses after "Create developer, app and credential" until an administrator approves.

Scripting onboarding with the Management API

The console is fine for a first try. For repeatable setup, the Apigee API at https://apigee.googleapis.com/v1 does the same. The commands below use gcloud for a token. Names, the organization and hostname are placeholders.

export ORG=my-apigee-org
export TOKEN=$(gcloud auth print-access-token)
export API=https://apigee.googleapis.com/v1/organizations/$ORG

# 1. Register a developer (email, firstName, lastName and userName are required)
curl -s -X POST "$API/developers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"dev@partner.example","firstName":"Dana","lastName":"Partner","userName":"dana"}'

# 2. Create the product (save the JSON shown above as product.json)
curl -s -X POST "$API/apiproducts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @product.json

# 3. Create an app for that developer; Apigee generates a key for it
curl -s -X POST "$API/developers/dev@partner.example/apps" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"partner-checkout-app","apiProducts":["partner-orders-read"]}' \
  | tee app.json

# 4. Read the consumer key from the credentials list and call the API
KEY=$(jq -r '.credentials[0].consumerKey' app.json)
curl -s -H "x-api-key: $KEY" "https://api.example.com/orders/v1/orders?limit=5"

The proxy must already be deployed (product creation can fail if a referenced proxy does not exist in the environment) and api.example.com stands for a hostname on your environment group.

Developer portals

Developers need somewhere to find APIs, read documentation, register apps and get keys. Apigee's integrated portal is a managed answer. Per the documentation it generates reference documentation from OpenAPI specs, lets developers sign up and register apps themselves, stores apps and keys in Apigee, and supports audiences, a page editor and theming. Publishing an API to it is two steps: choose the product to expose, then attach the reference documentation, which can come from an OpenAPI document, an AsyncAPI document or a GraphQL schema. Apigee also documents Drupal-based portals as a customer-managed alternative; check the current docs for support in your edition before choosing one. Public products can be added to a portal; private and internal-only products are normally granted to apps by hand from the console or API.

Monetization, briefly

Apigee has a monetization feature in which rate plans attach to API products, so a product can be sold by consumption bands or similar models. It is an add-on with its own setup and constraints (for example, product names used with monetization must not have trailing spaces), so treat this lesson as the foundation and read the monetization documentation before designing pricing.

The API lifecycle

An API is not "done" when it ships. Treat it as a product with a life: it is designed, mocked, built, published, watched, then eventually deprecated and retired.

Custom attributes hold extra information on a product. Using one to flag deprecation, which a proxy reads at runtime to add the header or raise a fault, is this lesson's suggested design, not a documented feature, so test it in your own environment.

Three use cases

Mobile is worth a second look. A key compiled into an app can be extracted by anyone who has the app, so the key only identifies the app and does not authenticate a user. User-level authorisation needs tokens, which the security lesson covers.

Decision guide

• One product or several for the same proxy? Several, when different consumers need different operations, quotas or approval. One, when everyone gets the same offer.
• New proxy or new revision? A revision for compatible changes, a new proxy and base path for breaking ones.
• Public, private or internal-only? Public for products you want on a portal. Private or internal-only describes who the product is meant for, and apps get it by being added manually.
• Auto or manual approval? Manual wherever a human should know who is getting access, such as partners and anything with sensitive data.
• Quota on the product or in the proxy? Put the number on the product so that it travels with the offer, and make sure a Quota policy in the proxy applies it.

In practice: opening a partner Orders API

The situation

A retailer has an internal orders service used by its web shop. Three logistics partners now want to read order status and create orders. Today each partner gets a VPN account and direct access to the service, with no per-partner limits, and one partner's batch job slowed the shop last quarter (assumed). The team has four weeks (assumed) to offer a proper partner API, and must be able to turn off a single partner without affecting others.

Starting architecture

How to read it: every partner shares one route and one set of limits. Nothing identifies which partner caused load.

What changes

1. Write the contract. Create the OpenAPI spec for list, get and create orders, with the cursor pagination, the standard error shape and a required Idempotency-Key on POST. Review it with the three partners.
2. Mock first. Generate a no-target proxy from the spec and add AssignMessage policies that return sample responses, so partners can start integration before the backend is ready.
3. Build the real proxy. Generate a reverse proxy from the same spec with base path /orders/v1 and the orders service as target. Add VerifyAPIKey and a Quota policy in the PreFlow. Deploy to a test environment, then to production.
4. Design two products. partner-orders-read (GET operations, 1,000 requests per hour on the list, assumed) and partner-orders-write (adds POST, lower quota, manual approval). Both point at the same proxy.
5. Onboard. Publish both products on the integrated portal. Each partner registers a developer and an app, asks for the read product, and the team approves the write product by hand after contract checks.
6. Cut over and close the VPN route once partner traffic is proven through the gateway.

Result

What the learner should see: each partner has an app and a key of its own, so analytics and quota counters are separated per app. Revoking one app's credential stops that partner and nobody else. A partner that exceeds its quota gets a 429-style error in the standard error shape (the exact status and fault come from the Quota policy configuration), and the orders service sees only traffic that passed the gateway. When the team later needs a breaking change, a /orders/v2 proxy and new products run beside v1 while v1 is marked deprecated.

Architect's notes

• Start with the product, not the proxy. Ask "what will we offer and to whom" before "what paths exist". Products are cheap to add; renaming a published product breaks consumers and docs.
• Keep products coarse enough to explain. Ten products with subtle differences confuse developers and the support desk. Three tiers read clearly.
• A product is an enforcement point only with policies behind it. Review every proxy for the presence of VerifyAPIKey or OAuth. A missing policy means open access, and no error will tell you.
• Plan for propagation delay. Product and credential changes can take minutes. Do not rely on a revoke being instant during an incident; add a gateway-side deny for emergencies.
• Version for the slowest consumer. Mobile apps in the field and partner release cycles set your overlap period, not your own sprint calendar.
• Cost. Every extra major version is another proxy to patch and test. Budget a sunset date when the version launches.
• When not to use products. For a purely internal call between two services in one trust zone, a product and key per caller may be heavier than the problem; a mesh or platform identity may be enough (see API gateway and service mesh).

Common mistakes

• Creating a product with no proxies. An unscoped product is a security risk and hard to reason about. Always list the proxies and operations.
• Assuming a product quota is enforced. Product quota values do nothing until a Quota policy runs in the proxy. Add the policy and test with a low limit.
• Treating revisions as versions. A revision is a deployment snapshot. Breaking the contract inside a revision surprises every consumer. Cut a new base path for breaking changes.
• One shared key for all consumers. You lose per-consumer limits, analytics and the ability to revoke one party. Issue one app per consumer.
• Hiding a key in a mobile app and calling it security. Treat the key as an identifier and add OAuth user tokens.
• Changing a spec without regenerating or reviewing the proxy. The proxy and the published docs drift apart. Review spec changes as part of the proxy change and automate the check in CI.
• Matching error text in clients. Fault messages can change. Clients should switch on error codes in your own contract.
• Forgetting the portal audience. A product marked private may not appear to developers who expect it. Check access level and portal audiences together.

Key takeaways

• A proxy is the implementation; a product is the offer; an app is the consumer; a credential links an app to products.
• Design first with OpenAPI: Apigee can generate a reverse proxy or a no-target proxy (a base for a mock) from the spec, with one conditional flow per operation.
• Keep one spec and one proxy per API version, with one product per offer: a simple one-to-one mapping is the default, and several products on one proxy is fine when offers differ.
• Implement versions as base paths, one proxy per major version, and keep revisions for compatible changes.
• A product bundles operations (proxy, path, methods, quota), environments, approval, scopes and attributes, but enforcement needs VerifyAPIKey or OAuth and Quota policies.
• Use one app per consumer and rotate keys by adding a second credential before revoking the first.
• Plan deprecation from day one: attribute, Sunset header, per-app usage tracking, then retirement.
• Expect cache delays of minutes for product and credential changes.

Practice exercises

Starter (about 30 min): Write an OpenAPI spec for a small API of your choice (three paths, one with a path parameter, a standard error schema). In the Apigee console, generate a reverse proxy from it against the public mock target at https://mocktarget.apigee.net (edit the server URL first), deploy it, and call it with curl. Note how many conditional flows were generated and why.

Intermediate (about 2 h): Create two products for one proxy: a read-only product and a read-write product with different quotas. Register one developer and two apps, one per product. Add VerifyAPIKey and Quota policies to the proxy. Prove with curl that the read-only app gets a 401 on POST, and that exceeding the quota (set it very low) returns an error. Script the onboarding with the Management API calls from this lesson.

Advanced (half a day): Design a versioning and deprecation plan for an API with 20 consumers. Produce the v2 spec, a /v2 proxy and new products. Implement a proxy flow that reads a custom attribute on the v1 product and adds a Sunset header to every v1 response. Write the runbook for retirement, including how you will measure remaining usage per app and how you will revoke credentials. Add a mock proxy for v2 so consumers can start early.

Related reading

• Course overview — the full course map.
• Apigee fundamentals and request flow — organizations, environments and where policies run.
• Building Apigee API proxies — flows, endpoints and policies behind the proxies that products point to.
• Securing APIs in Apigee — OAuth, JWT and threat protection beyond API keys.
• Traffic management in Apigee — enforcing the quotas that products declare.
• Fault handling, debugging and monitoring — error contracts and per-app analytics.
• Environments, revisions and deployment — how revisions reach each environment.
• Capstone: an Orders API on Apigee — apply everything end to end.
• API design for system designers — REST conventions in more depth.
• API gateway and service mesh — where a gateway fits in a wider architecture.
• Apigee and microservices — the gateway pattern in a service architecture.

Official documentation

• Introduction to API products
• Managing API products
• Registering apps and managing API keys
• Creating an API proxy from an OpenAPI Specification
• Building a simple API proxy
• About environments and environment groups
• VerifyAPIKey policy
• RaiseFault policy
• Building your integrated portal
• Publishing your APIs to a portal
• What is Apigee API hub?
• Apigee API reference: ApiProduct resource
• Apigee API reference: developer apps