3 - Gateway Development

©2012 Apigee #1

V 4.21.0!May, 2013!

API Development in the Apigee Platform!

©2012 Apigee #2

Agenda!

Requirements •  Laptop •  Internet Connec-on •  Browser (Chrome or Firefox – not IE) •  Access to Email (for account setup)

Good To Have •  Eclipse (or a good XML editor like TextWrangler) •  Linux Shell with curl (suppor-ng hFps)

What Are You Going to Need?!

©2012 Apigee #3

Agenda!

An Aging Database in a Brave New World!

Slow Backend (PHP & Perl – yes, Perl) Inconsistent URI Structure No App Security No Usage Stats Limited Func-onality

©2012 Apigee #4

Agenda!

How are we going to use Apigee to fix this?!

Simplify Your URL Design Backend Security with Basic Auth Security & Tracking with Products and Developers and Apps

Cache the Response Use Callout to Translate the Payload

©2012 Apigee #5

Building the Facade!

API Contract/Governance !The goal is to provide a consistent, easy-‐to-‐understand API and make it as easy as possible for developers to engage with your services.

©2012 Apigee #6


Managing Flows Through Policies!

Proxy Flow Request

PreFlow PostFlow Conditional Flows

Response

PostFlow Conditional Flows

PreFlow

Target Flow Request

PreFlow PostFlow Conditional Flows

Response

Postflow Conditional Flows

Preflow

target system

client

Policies •  -‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐ •  -‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐ •  -‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐

©2012 Apigee #7

Getting Started!

$ curl -‐u myname:mypass -‐X GET hFps://{mgt server domain}/organiza-ons/{org}/apis

Accessing Apigee!

©2012 Apigee #8

Getting Started!

Adding Accounts!

©2012 Apigee #9


Simplify your URL Structure!

©2012 Apigee #10


The JokeIndex API!Target:

hFp://jokeindex.com/services/20/api Services:

/rated?rate={G, PG, R} Returns list of jokes by ra-ng based on query parameter rate /joke?jokeid={id} Returns full body of the joke based on query parameter jokeid /cat Returns list of categories /cat?ca5d={ca5d} Returns list of jokes by query parameter ca5d

©2012 Apigee #11


Create an API: Define the proxy and backend!

©2012 Apigee #12


Name: A public name for the AP Service (seen in Analy-cs)

Proxy Endpoint: Choose if more than one inbound proxy in this API (usually “default”)

Path: Target path suffix (just the bit acer the Backend Server URL from the previous step)

Verb: Separate resources are defined by separate verbs (GET/POST/PUT/DELETE)

Create an API: Add Resources!

©2012 Apigee #13


Deployment Environments!The API is automa-cally deployed to the “test” environment using the defined Virtual Host

©2012 Apigee #14


Test the Endpoint!

©2012 Apigee #15

Securing the Target!

Secure your Target Services!

©2012 Apigee #16


Managing Policies: Add a Policy!

©2012 Apigee #17


Managing Policies!

©2012 Apigee #18


Managing Policies!

©2012 Apigee #19


Managing Policies!

©2012 Apigee #20


Managing Policies!

©2012 Apigee #21


Managing Policies!

©2012 Apigee #22


Test the Endpoint: Success!!

©2012 Apigee #23

Securing the Front-end!

Secure the API with API Keys!

©2012 Apigee #24

Securing the Front-end!

Verify API Key!Applica-on key verifica-on blocks unwelcome traffic and populates variables for other policies (such as Quota) and sets variables for tracking in Analy-cs

<?xml version="1.0" encoding="UTF-‐8" standalone="yes"?> <VerifyAPIKey enabled="true" con-nueOnError="false" async="false" name="VerifyAPIKey-‐1"> <DisplayName>Verify API Key 1</DisplayName> <FaultRules/> <Proper-es/> <APIKey ref="request.queryparam.apikey"></APIKey> </VerifyAPIKey> Configurable query param

(default “apikey”)

©2012 Apigee #25

Products, Developers and Apps!

An API product is a collec-on of API resources combined with a service plan and presented to developers as a bundle.

Manage App Developers via Products!

©2012 Apigee #26


Name: A public name for the API (seen by developers)

Key Approval Type: API Keys can either be automa-c or require human approval

DescripDon: Human Readable Descrip-on

Create a Product!

Quota: Variable which can op-onally be used by Quota Policy

Environment: The deployment environment this product is available in

©2012 Apigee #27


Create a Product: Add API Resources!Restrict access to your API by specifically lis-ng resources the Product can consume

©2012 Apigee #28


Add Developer!

©2012 Apigee #29


An API Key (or consumer_id) can gives a developer access to mul-ple products.

Add an App!

And… A developer can have mul-ple apps with the same or different products

©2012 Apigee #30


Add an App!

©2012 Apigee #31


Add an App!You may need to approve access to each product – the keys are shown by the product, but note that the are the same keys for all products (it’s the app key, not the product key).

©2012 Apigee #32

Building a Callout!

We can add func-onality such as transla-on tools by adding callouts to the flow

Callout to a Third Party Service!

©2012 Apigee #33

Building a Callout!

Just a few steps…!

ExtractVariables: Set Apigee variables from the JSON Payload

AssignMessage: Prepare a payload for the callout to Bing (need to get a token)

ServiceCallout: Callout to Bing Auth Server

ExtractVariables: Get the Bing access_token from the JSON Payload

AssignMessage: Prepare a payload to be translated

ServiceCallout: Callout to Bing Translate tool

ExtractVariables: Get the translated joke from XML payload

AssignMessage: Create a new payload to return to the client.

and (request.header.Accept-‐Language = NULL)</Condi-on> </Flow>

©2012 Apigee #34

Custom Code!

JavaScript Callout!There are two parts to a JavaScript callout – the policy aFachment that calls to the script, and the script itself.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript timeLimit="200" enabled="true" continueOnError="false" async="false" name="JavascriptCleanBingMess"> <DisplayName>JavascriptCleanBingMess</DisplayName> <FaultRules/> <Properties/> <IncludeURL>jsc://ReplaceNewlines.js</IncludeURL> <ResourceURL>jsc://ReplaceNewlines.js</ResourceURL> </Javascript>

var mytrans = context.getVariable("bing.translation");!!myvar = myvar.replace("\n", "\\n", "g");!myvar = myvar.replace("\"", "\"", "g");!!context.setVariable("bing.translation", myvar);!

JavaScript Callout policy

Script File

©2012 Apigee #35

Caching!

Cache API Service Calls!

©2012 Apigee #36

Caching!

Cache Policy!A Cache Policy allows the app to receive a cached response from Apigee without having to go to the backend. This can greatly reduce response -me and latency.

<ResponseCache name="ResponseCache"> <CacheResource>mycache</CacheResource> <Scope>Global</Scope> <CacheKey> <Prefix>apigee</Prefix> <KeyFragment ref="request.uri" /> <KeyFragment ref="request.header.Accept-Language" /> <KeyFragment ref="request.header.Accept" /> </CacheKey> <SkipCacheLookup>{condition}</SkipCacheLookup> <SkipCachePopulation>{condition}</SkipCachePopulation> <ExpirySettings> <TimeoutInSec>300</TimeoutInSec> OR <TimeoutInSec ref="response.header.timeout" /> </ExpirySettings> </ResponseCache>

©2012 Apigee #37

Caching!

Cache Policy!A Cache Policy allows the app to receive a cached response from Apigee without having to go to the backend. This can greatly reduce response -me and latency.

<ResponseCache name="ResponseCache"> <CacheResource>mycache</CacheResource> <Scope>Global</Scope> <CacheKey> <Prefix>apigee</Prefix> <KeyFragment ref="request.uri" /> <KeyFragment ref="request.header.Accept-Language" /> <KeyFragment ref="request.header.Accept" /> </CacheKey> <SkipCacheLookup>{condition}</SkipCacheLookup> <SkipCachePopulation>{condition}</SkipCachePopulation> <ExpirySettings> <TimeoutInSec>300</TimeoutInSec> OR <TimeoutInSec ref="response.header.timeout" /> </ExpirySettings> </ResponseCache>

<ResponseCache name="ResponseCache"> <CacheResource>mycache</CacheResource> <Scope>Global</Scope> <CacheKey> <Prefix>apigee</Prefix> <KeyFragment ref="request.uri" /> <KeyFragment ref="request.header.Accept-Language" /> <KeyFragment ref="request.header.Accept" /> </CacheKey> <SkipCacheLookup>{condition}</SkipCacheLookup> <SkipCachePopulation>response.status.code != 200</SkipCachePopulation> <ExpirySettings> <TimeoutInSec>300</TimeoutInSec> OR <TimeoutInSec ref="response.header.timeout" /> </ExpirySettings> </ResponseCache>

Build a unique key based on variables

Set rules to avoid popula-ng bad data in cache

©2012 Apigee #38

Caching!

curl -‐H "content-‐type:text/xml" -‐X POST -‐d \ '<Cache name="myCache"> <Descrip-on>A Cache resource for the test environment.</Descrip-on> <MaxElementsInMemory>100</MaxElementsInMemory> <MaxElementsOnDisk>1000</MaxElementsOnDisk> <OverflowToDisk>true</OverflowToDisk> <Persistent>false</Persistent> <ExpirySexngs>

<TimeoutInSec>300</TimeoutInSec> </ExpirySexngs> <Compression>

<MinimumSizeInKB>1024</MinimumSizeInKB> </Compression> </Cache>' \ hFps://api.enterprise.apigee.com/v1/o/{org}/environments/{env}/caches \ -‐u username:password

Create a Cachestore!Each environment needs its own cachestore

©2012 Apigee #39

Behind the UI!

/apiproxy: Root directory of Apigee bundle

/apiproxy/proxies: Client policy execu-on configura-on files. (default.xml)

/apiproxy/targets: Backend policy execu-on configura-on files. (default.xml)

/apiproxy/policies: Policy execu-on configura-on files. (policy_name.xml, policy_name2.xml, etc.)

/apiproxy/resources: JavaScript, Java, and Python files used by policies

The Apigee “Bundle” (Editing Source Files)!

©2012 Apigee #40

Behind the UI!

Editing inbound Proxy Flows!<?xml version="1.0" encoding="UTF-‐8" standalone="yes"?> <ProxyEndpoint name="default"> <Descrip-on>Default Proxy to create flows on an API</Descrip-on> <FaultRules/> <Flows> <Flow name="joke detail"> <Descrip-on>Joke detail</Descrip-on> <Request> <Step> <FaultRules/> <Name>myQuota</Name> </Step> </Request> <Response/> <Condi-on>(proxy.pathsuffix MatchesPath "/joke") and (request.verb = "GET") and (request.header.Accept-‐Language = NULL)</Condi-on> </Flow> </Flows> <HTTPProxyConnec-on> <BasePath>/v1</BasePath> <Proper-es/> <VirtualHost>default</VirtualHost> </HTTPProxyConnec-on> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> <Condi-on /> </RouteRule> </ProxyEndpoint>

Step Defini-ons (Policy AFachments)

Connec-on Defini-on

proxies/default.xml

©2012 Apigee #41

Behind the UI!

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <TargetEndpoint name="default"> <Description>Apigee auto generated target endpoint</Description> <FaultRules/> <PreFlow name="PreFlow"> <Request> <Step> <FaultRules/> <Name>AddAuthHeader</Name> </Step> </Request> <Response/> </PreFlow> <HTTPTargetConnection> <Properties/> <URL>http://weather.yahooapis.com</URL> </HTTPTargetConnection> </TargetEndpoint>

Target Name (called by proxies/default.xml)

TargeF URL (called by proxies/default.xml)

targets/default.xml

Editing Target Flows!

©2012 Apigee #42

Target Flows can also be variablized for each environment (eg point test to a sandbox.api and prod to prod.api)

Behind the UI!

Editing Target Flows!

curl http://host:port/v1/organizations/{organization}/environments/{environment}/targetservers!

<TargetServer name="TS1"> <Host>dev.targetserver.com</Host> <Port>80</Port> <IsEnabled>true</IsEnabled> </TargetServer>

<TargetEndpoint name=”default"> <Description>Making targets loadbalance</Description> <HttpTargetConnection> <LoadBalancer> <Server name="TS1" /> <Server name="TS2" /> </LoadBalancer> </HttpTargetConnection> </TargetEndpoint>

©2012 Apigee #43

Behind the UI!

<?xml version="1.0" encoding="UTF-‐8" standalone="yes"?> <Quota async="false" con-nueOnError="false" enabled="true" name=”myPolicy"> <DisplayName>Quota Policy</DisplayName> <FaultRules/> <Proper-es/> <Allow count="2000" countRef="request.header.allowed_quota"/> <Interval ref="request.header.quota_count">1</Interval> <Distributed>false</Distributed> <Synchronous>false</Synchronous> <TimeUnit ref="request.header.quota_-meout">month</TimeUnit> </Quota>

policies/myPolicy.xml

Name used in Step Defini-ons

Configuring Policy Definitions!

©2012 Apigee #44

Deployment Methodologies !

UI Intui-ve but limited messaging

Script As flexible as you want it to be

Maven Integrate with your development lifecycle

©2012 Apigee #45

Deployment Script!

deploy.sh Simple script to execute API calls to Apigee management system

ConfiguraDon ConsideraDons Variablized URIs

url: hFp(s) and domain name for Apigee environment: Test/Prod etc org: Apigee group (usually doesn’t change) applica-on: Group of services (revision control) creden-als: Your login and password

$url/v1/organiza-ons/$org/apis/$applicaDon/revisions/1/deployments?ac-on=undeploy&env=$environment

applica-on=weather_api org=testorama Environment=prod [email protected]:mypass url=hFps://api.enterprise.apigee.com

©2012 Apigee #46

Deployment Script!


Un-‐deploy & delete previous version Delete previous deployment from server Delete local “applica-on.zip” file

curl -‐u $creden-als "$url/v1/organiza-ons/$org/apis/$applica-on/revisions/1/deployments? ac-on=undeploy&env=$environment" -‐X POST -‐H "Content-‐Type: applica-on/octet-‐stream” curl -‐u $creden-als -‐X DELETE "$url/v1/organiza-ons/$org/apis/$applica-on/revisions/1” rm -‐rf $applica-on.zip

©2012 Apigee #47

Deployment Script!


Create the new bundle and deploy Zips the local ./apiproxy folder Posts zip file to Apigee Ac-vates bundle in Apigee

zip -‐r $applica-on.zip apiproxy curl -‐v -‐u $creden-als "$url/v1/organiza-ons/$org/apis?ac-on=import&name=$applica-on" -‐T $applica-on.zip -‐H "Content-‐Type: applica-on/octet-‐stream" -‐X POST curl -‐v -‐u $creden-als "$url/v1/organiza-ons/$org/apis/$applica-on/revisions/1/deployments?ac-on=deploy&env=$environment" -‐X POST -‐H "Content-‐Type: applica-on/octet-‐stream"

©2012 Apigee #48

Thanks!

Documents

3 - Gateway Development