Skip to content

developer-guide.md

Latest commit

 

History

History
365 lines (289 loc) · 8.89 KB

developer-guide.md

File metadata and controls

365 lines (289 loc) · 8.89 KB

Apigee Development Framework - Developer Guide

Table of Contents

  1. Overview
  2. Getting Started
  3. Framework Components
  4. Policies
  5. Shared Flows
  6. Naming Conventions
  7. Best Practices
  8. Examples
  9. Deployment
  10. Troubleshooting

Overview

The Apigee Development Framework provides a comprehensive set of reusable policies and shared flows for building robust API proxies in Google Apigee. This framework follows industry best practices and provides consistent patterns for common API development scenarios.

Key Features

  • Security Policies: CORS, OAuth2, API Key validation
  • Traffic Management: Rate limiting, spike arrest
  • Data Transformation: JSON/XML conversion
  • Monitoring: Response caching, logging
  • Error Handling: Standardized error responses
  • Logging: Comprehensive audit logging with sensitive data masking

Getting Started

Prerequisites

  • Google Apigee Edge account
  • Apigee CLI tools installed
  • Basic understanding of Apigee concepts

Installation

  1. Clone or download the framework
  2. Import shared flows into your Apigee organization
  3. Copy policies to your API proxy projects
  4. Reference the components in your proxy configurations

Quick Start Example

<!-- In your proxy endpoint -->
<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Name>security-cors-v1</Name>
            <Condition>request.verb == "OPTIONS"</Condition>
        </Step>
        <Step>
            <Name>authentication-oauth2-v1</Name>
        </Step>
        <Step>
            <Name>logging-audit-v1</Name>
        </Step>
    </Request>
</PreFlow>

Framework Components

Directory Structure

framework/
├── policies/                 # Reusable policies
│   ├── security/            # Security-related policies
│   ├── traffic/             # Traffic management policies
│   ├── transformation/      # Data transformation policies
│   └── monitoring/          # Monitoring and analytics policies
├── shared-flows/            # Reusable shared flows
│   ├── logging/             # Logging and audit flows
│   ├── error-handling/      # Error handling flows
│   ├── authentication/      # Authentication flows
│   └── utilities/           # Utility flows
├── examples/                # Example implementations
├── templates/               # API proxy templates
└── docs/                    # Documentation

Policies

Security Policies

CORS Policy (security-cors-v1)

Handles Cross-Origin Resource Sharing for web applications.

Usage:

<Step>
    <Name>security-cors-v1</Name>
    <Condition>request.verb == "OPTIONS"</Condition>
</Step>

Configuration:

  • Allowed origins: Configurable via policy
  • Allowed methods: GET, POST, PUT, DELETE, OPTIONS
  • Allowed headers: Content-Type, Authorization, X-Requested-With, X-API-Key
  • Exposed headers: X-Request-ID, X-Response-Time

OAuth2 Policy (security-oauth2-v1)

Validates OAuth2 access tokens.

Usage:

<Step>
    <Name>security-oauth2-v1</Name>
</Step>

Supported Grant Types:

  • client_credentials
  • authorization_code
  • refresh_token

API Key Policy (security-api-key-v1)

Validates API keys from request headers.

Usage:

<Step>
    <Name>security-api-key-v1</Name>
</Step>

Traffic Management Policies

Rate Limiting (traffic-rate-limit-v1)

Implements quota-based rate limiting.

Configuration:

  • Default: 1000 requests per hour
  • Identifier: client_id
  • Distributed: true

Spike Arrest (traffic-spike-arrest-v1)

Prevents traffic spikes.

Configuration:

  • Rate: 10 requests per second
  • Identifier: client_id

Transformation Policies

JSON to XML (transformation-json-to-xml-v1)

Converts JSON responses to XML format.

Usage:

<Step>
    <Name>transformation-json-to-xml-v1</Name>
    <Condition>request.header.accept == "application/xml"</Condition>
</Step>

XML to JSON (transformation-xml-to-json-v1)

Converts XML responses to JSON format.

Monitoring Policies

Response Cache (monitoring-response-cache-v1)

Caches responses for performance optimization.

Configuration:

  • Cache key: URI + query parameters
  • Timeout: 300 seconds
  • Scope: Global

Shared Flows

Logging Shared Flow (logging-audit-v1)

Comprehensive logging with sensitive data masking.

Features:

  • Request/response logging
  • Sensitive data masking
  • Structured log format
  • External system integration

Usage:

<Step>
    <Name>logging-audit-v1</Name>
</Step>

Sensitive Data Masking:

  • Passwords, tokens, API keys
  • Credit card numbers
  • Social Security Numbers
  • Email addresses
  • Phone numbers

Error Handling Shared Flow (error-handling-standard-v1)

Standardized error responses.

Features:

  • Consistent error format
  • Proper HTTP status codes
  • Error logging
  • Standard headers

Usage:

<FaultRule name="ErrorHandling">
    <Step>
        <Name>error-handling-standard-v1</Name>
        <Condition>fault.name != "error-handling-standard-v1"</Condition>
    </Step>
</FaultRule>

Authentication Shared Flow (authentication-oauth2-v1)

OAuth2 authentication flow.

Features:

  • Token extraction
  • Token validation
  • Context setting

Utilities Shared Flow (utilities-request-validation-v1)

Request validation utilities.

Features:

  • Header validation
  • Parameter validation
  • JSON schema validation

Naming Conventions

Policies

Format: {category}-{function}-{version}

  • Example: security-cors-v1
  • Example: traffic-rate-limit-v1

Shared Flows

Format: {purpose}-{function}-{version}

  • Example: logging-audit-v1
  • Example: error-handling-standard-v1

Variables

Format: {scope}.{category}.{name}

  • Example: request.header.authorization
  • Example: response.status.code

Files

  • Policies: {policy-name}.xml
  • Shared Flows: {shared-flow-name}.xml
  • JavaScript: {function-name}.js

Best Practices

1. Policy Organization

  • Group related policies in folders
  • Use consistent naming conventions
  • Document policy purposes and configurations

2. Error Handling

  • Always implement fault rules
  • Use standardized error responses
  • Log errors for monitoring

3. Security

  • Implement authentication for all endpoints
  • Use HTTPS for all communications
  • Mask sensitive data in logs

4. Performance

  • Use response caching where appropriate
  • Implement rate limiting
  • Monitor response times

5. Logging

  • Log all requests and responses
  • Mask sensitive data
  • Use structured log formats

Examples

Basic API Proxy

See examples/sample-api-proxy/ for a complete example demonstrating:

  • CORS handling
  • OAuth2 authentication
  • Rate limiting
  • Request validation
  • Comprehensive logging
  • Error handling

Custom Policy Usage

<!-- Custom rate limiting -->
<Step>
    <Name>traffic-rate-limit-v1</Name>
    <Condition>request.header.x-client-tier == "premium"</Condition>
</Step>

Deployment

Using Apigee CLI

# Deploy shared flows
apigeetool deploySharedFlow -o {org} -e {env} -n logging-audit-v1 -d framework/shared-flows/logging/

# Deploy API proxy
apigeetool deployProxy -o {org} -e {env} -n sample-api-proxy -d framework/examples/sample-api-proxy/

Using Maven

<plugin>
    <groupId>com.apigee.edge</groupId>
    <artifactId>apigee-edge-maven-plugin</artifactId>
    <version>1.1.0</version>
</plugin>

Troubleshooting

Common Issues

1. Policy Execution Errors

  • Check policy names and references
  • Verify policy configurations
  • Review error logs

2. Authentication Failures

  • Verify OAuth2 configuration
  • Check token format
  • Validate client credentials

3. Logging Issues

  • Check external system connectivity
  • Verify log format
  • Review sensitive data masking

4. Performance Issues

  • Monitor response times
  • Check cache configurations
  • Review rate limiting settings

Debugging Tips

  1. Enable debug logging
  2. Use trace tool in Apigee Edge
  3. Check policy execution order
  4. Verify variable assignments

Support

For issues and questions:

  1. Check the documentation
  2. Review example implementations
  3. Consult Apigee Edge documentation
  4. Contact the framework maintainers

Version History

v1.0.0 (2025-01-27)

  • Initial framework release
  • Core policies and shared flows
  • Comprehensive logging with data masking
  • Example implementations
  • Complete documentation