[Client - Project Name]
Functional & Non-Functional Requirements
[version]
[Author]
©2013 Apigee. All Rights Reserved.
Purpose
1
Introduction
1
About [Project Name]
1
Project Objectives
1
High Level Functional Description
1
Client-Side Requirements
2
Apigee Clients
2
Connectivity
2
Security Requirements
2
Transport Security
2
Application and User Identification and Authorization
2
User Identity Validation
2
Client IP Control
2
Target Requirements
3
Apigee Targets
3
Connectivity
3
Load Balancing
3
Security Requirements
3
Transport Security
3
Apigee Identification and Authorization
3
User Identity Forwarding
3
IP Control
3
Data Security
3
PCI Requirement
Operational Requirements
3
4
Datacenter/Region Requirements
4
Failover Requirements
4
Client-Side Load Balancing Requirements
4
Availability Expectations
4
Organizations and Environments
4
API Development and Deployment Process
Performance
Performance Expectations
4
5
5
Target Response Times
5
Target Throughput
5
Apigee Response Times
5
Apigee Throughput
5
Solution Requirements
6
©2013 Apigee. All Rights Reserved.
API Requirements
6
Traffic Management
6
Security
6
Mediation
6
Analytics Requirements
6
Custom Reports
6
Custom Variables
7
Data Retention and Archival Strategy
7
Custom Data Extraction
7
AppServices Requirements
7
Organizational Structure
7
Data Import Requirements
7
Data Export Requirements
7
Security
7
Collections
7
Entities
8
Developer Portal Requirements
8
Branding
8
Security
8
API Console
8
API Documentation
8
Developer and Application Statistics
8
Browser Support
8
Onboarding
8
Application Onboarding
8
Developer Onboarding
8
Support
9
Operational Monitoring Requirements
9
Apigee Only Health check
9
Target Only Health check
9
Complete API Health check
9
Maintenance Expectations
Testing Considerations
Functional Testing
9
10
10
Testing Approach
10
Test Cases
10
Performance Testing
10
Testing Approach
10
Test Cases
10
Software Maintenance Considerations
11
System Maintenance
11
Training
12
©2013 Apigee. All Rights Reserved.
Purpose
This document is to capture the comprehensive set of functional and non-functional requirements. The requirements are
specific to the Apigee implementation and cover all aspects: design, architecture, infrastructure (on-prem), and
interactions of Apigee with other components. The details captured will be further refined into user stories and this
document will be archived as the team executes to the prioritized user stories.
Functional requirements should detail specific behaviors or functions for the solution (e.g. REST to SOAP mediation,
business rules, Oauth 2.0 Authorization). Non-functional requirements specify the criteria that can be used to measure
the operation of the system (e.g PCI Compliant, Supports Failover, Disaster Recovery, Performance).
Introduction
This section introduces the solution and outlines the goals for this project.
About [Project Name]
[Briefly explain what this client’s project/API Program is about, value provided by client’s APIs, what business
problem do they solve, what data/processes are they exposing]
[What type of API clients will communicate with Apigee, e.g. mobile, web, B2B/C]
Project Objectives
[Explain primary objectives for the Apigee integration – objectives of the Apigee project. What are the success
criteria?]
High Level Functional Description
[Explain the key functionality to be used in this solution and why it’s important to the client – also mention any
custom pieces to be developed as part of this solution which don’t exist in the core product]
Edge
Feature
Why it’s important
Analytics
Feature
Why it’s important
Developer Portal
Feature
Why it’s important
AppServices
Feature
Why it’s important
©2013 Apigee. All Rights Reserved.
Client-Side Requirements
This chapter captures requirements relating to the interface between API client and
Apigee.
Apigee Clients
[What are the client systems/applications? Types of client systems; browser, mobile apps, B2B, ESB, internal
systems, external systems, etc.]
Connectivity
[Explain the protocol and means by which API clients will connect to Apigee, e.g. HTTP, HTTPS (one-way or
mutual), message queuing, CDN, VPN, dedicated network, internal network etc.]
Security Requirements
Transport Security
[How will the transport be secured? If SSL, explain who has ownership of generating and maintaining the
certificates]
Application and User Identification and Authorization
[Is API client application required to be identified – analytics, visibility, etc. If so how, e.g. application key, client
SSL, etc.)]
[If client SSL will be used for identification, explain who has ownership of generating, maintaining and
distributing the certificates. Ask either customer requires the use of Two-way SSL or One-way, where customer
requires SSL termination on (Apigee’s components or Client’s components). How will customer transfer the
certificates to Apigee, FTP (customer’s or Apigee’s), encrypted ZIP in an email and password out-of-band,
encrypted email – mention the encryption protocol to be used, Bitmessage, OpenPGP, etc.]
[Is API client application required to be authenticated, where are credentials stored (Apigee KMS, AppServices or
customer side), how will the credentials presented be validated]
[If OAuth will be used explain the grant types to be supported, 3-Leg vs. 2-Leg, credentials types, access/refresh
token intervals, scopes, and other characteristics]
User Identity Validation
[Explain how user credentials presented will be validated, where are credentials stored]
Client IP Control
[Explain whether clients will be IP whitelisted, IP Blacklisted, Dedicated IPs. If they will be, explain customer’s
expectations on how IP list will be maintained. If list is cacheable, TTL of this cache]
©2013 Apigee. All Rights Reserved.
Target Requirements
This chapter captures requirements relating to the communication between Apigee
and target systems.
Apigee Targets
[What are the target systems/applications? Type of target systems; B2B, internal systems, external systems,
message queues, SMTP, etc.]
Connectivity
[Explain the protocol and means by which Apigee will connect to target systems, e.g. HTTP, HTTPS (one-way or
mutual), message queuing, CDN, VPN, dedicated network, internal network etc.]
Load Balancing
[Does target systems have load-balancing capability or Apigee target load balancing should be used. If load
balancing will be used, explain algorithm to use (round robin, weighted, least connections), any fallback servers,
retry configuration, target node health monitoring configuration, max failures, session stickiness, etc.]
Security Requirements
Transport Security
[How will the transport be secured?]
[If SSL, explain who has ownership of generating and maintaining the certificates. If Apigee is generating selfsigned, would customer willing to sign the certificates]
Apigee Identification and Authorization
[Is Apigee required identify itself. If so how, e.g. shared secret, client credentials, mutual SSL, etc.) Ask either
customer requires the use of Two-way SSL or One-way, where customer requires SSL termination on (Apigee’s
components or Client’s components). If mutual SSL will be used for identification, explain who has ownership of
generating and maintaining the certificates. If client credentials will be used, explain who has the ownership of
generating, revoking and maintaining the credentials.]
[Is Apigee required to present client credentials to gain access to target systems, where are credentials stored,
how will the credentials be presented and validated]
User Identity Forwarding
[Does target systems need to knowledge of the identity of the end user? If so, how will Apigee pass this
information.]
IP Control
[Explain if Apigee IP addresses will need to be whitelisted, blacklisted by the target. If so, document IP addresses
here]
Data Security
[Does Customer require any special data privacy consideration with regards to APIs? Does Customer require
any special data privacy consideration with regards to Analytics data? Does Customer require any special data
privacy consideration with regards to the data in Logs? Does Customer require any special data privacy
consideration with regards to Reduction of payload data based on application type, user role, etc? Does
Customer require any special data privacy consideration with regards to Reduction of payload data from
responses? Does Customer require any special data privacy consideration with regards to Data storage (location,
context)? Does Customer require any special data privacy consideration with regards to personal sensitive data?
Does Customer require any special data privacy consideration with regards to CC Data?]
PCI Requirement
[Does Customer expect that its APIs will be subject to regulations around the storing and management of
sensitive data? Investigate if PCI is required for this solution. Note that northbound open HTTP connections are
not allowed by default in PCI organizations.]
©2013 Apigee. All Rights Reserved.
Operational Requirements
[Explain whether the solution will be deployed on-premise or Apigee Cloud. Explain the reasons why customer
wants to go this way.]
Datacenter/Region Requirements
[Document the number of datacenters to be used and locations of those datacenters.]
[If there are more than 1 DC, active/active or active/passive.]
[Investigate data confidentiality/protection requirements, e.g. data must not go outside EU, etc.]
[Understand the connectivity between datacenters if this is on-premise, speed, pipe type, etc.]
[Does all APIs required to pass through those datacenters, e.g. there might be specific APIs that must only be
deployed to EU due to data confidentiality laws, etc.]
[Data caching requirements for multi-datacenter – note the geolocation and data protection limitations.]
Failover Requirements
[Explain cross-region failover requirements (Apigee Cloud), on-premise datacenter failover requirements (onpremise).]
Client-Side Load Balancing Requirements
[Understand client-side how load balancing requirements, e.g. Dynect, on-premise load balancer, geo-IP, etc.]
Availability Expectations
[Explain customer’s availability expectations in terms of percentage availability. Make sure that datacenter or
region considerations above matches this expectation.]
Organizations and Environments
Organization
Environment
Purpose
Environment
Northbound Domain
Southbound Domain
API Development and Deployment Process
[Explain the progression of a specific version of API bundle through various environments, e.g. DEV -> QA ->
UAT -> PROD]
[If self-service, explain tools to be used to deploy APIs to Apigee environments, e.g. Apigee Enterprise UI, bash
scripting, maven, custom, etc.]
[If self-service, explain any continuous integration and deployment tool to be used, e.g. TeamCity, Jenkins, etc.]
©2013 Apigee. All Rights Reserved.
Performance
This chapter captures client’s traffic volume, performance and throughput
expectations.
Performance Expectations
Target Response Times
[Document client’s expectations in terms of expected API response time and/or latency range that target
system(s) are expected to have. If client has expectations/measurements for each individual API, include those
here. If client has no expectations or measurements planned in a future date, include that here as well.]
Target Throughput
[Express client’s expectations in terms of API throughout per second/minute for target system(s). If client has
expectations for each individual API, include those here. If client has no expectations, include that here as well.]
Apigee Response Times
[Express client’s expectations in terms of expected API response time and/or latency range that Apigee is
expected to contribute to overall response time. If client has expectations for each individual API, include those
here. If client has no expectations, include that here as well.]
Apigee Throughput
[Express client’s expectations in terms of API throughout per second/minute. If client has expectations for each
individual API, include those here. If client has no expectations, include that here as well.]
©2013 Apigee. All Rights Reserved.
Solution Requirements
API Requirements
[List the client-side API requirements and explain in detail, e.g.]
Requirement
Details
API Design
API Implementation
[Who is responsible for the design of the API]
[Who is responsible for the implementation in Apigee layer]
[Rates applied globally or based on request variable (like IP). How does
customer want to maintain the rate setting]
[Quotas applied globally or based on request variable (like IP). How
does customer want to maintain the quota allowance]
[Which resources, approximate size, TTL, globally distributed, etc.]
[Especially around data encoding (UTF-8) and languages to be
supported for Apigee responses (traffic management, security, etc.)]
Rate Limiting
Quotas
Caching
Internationalization/Localization
Traffic Management
Requirement
Rate Limiting
Quotas
Caching
Details
[Rates applied globally or based on request variable (like IP). How does
customer want to maintain the rate setting]
[Quotas applied globally or based on request variable (like IP). How
does customer want to maintain the quota allowance? Does customer
want the ability to reset quota as an administrative function? Does
customer want to expose quota used value in the response?]
[Which resources, approximate size, TTL, globally distributed, etc. Full
response or partial?]
Security
Requirement
Details
Threat Protection
Regular Expression Protection
OAuth
API Keys
Access Control
SAML Assertion
Attack Notification Protection
Reaction Against Attackers
Data Security
[E.g. IP based, etc.]
Mediation
Requirement
Details
JSON to XML
XML to JSON
XSL Transform
SOAP Message Validation
Key Value Map
Service Callouts
Analytics Requirements
[List API analytics requirements and explain in detail.]
Custom Reports
[List custom reports and their specifications that will be created during implementation to fulfill analytics
requirements.]
©2013 Apigee. All Rights Reserved.
Custom Variables
[List custom variables that will be pushed from Apigee Edge to Analytics to fulfill analytics requirements.]
Data Retention and Archival Strategy
[Describe how long analytics data will be retained – any specific data detention requirements for some APIs?]
[Are we required to archive old data? Explain procedures, archive interval, archive type (incremental, full)]
[Describe how will old/unwanted data be purged. Define “old” in terms of age of the data. Does customer
interested in a backup of data store before purging?]
Custom Data Extraction
[Describe any custom data extraction processes to be produced.]
[Document how customer will extract analytics data, what type of clients, e.g. scheduled process, standalone
client, web client, etc.?]
[Does customer want to use Analytics APIs? Note that API extracts data in JSON format – does this need to be
reformatted to meet client requirements for insertion into a data warehouse or business intelligence repository. If
customer will use a web client, do they need CORS support for Analytics API for JavaScript clients?]
AppServices Requirements
Organizational Structure
Data Import Requirements
[Document frequency of imports, e.g. hourly, daily, weekly, etc., number of entities to be imported per request.]
Data Export Requirements
[Document frequency of exports, e.g. hourly, daily, weekly, etc., number of entities to be exported per request.]
Security
[What are the client systems?]
Roles
Role
Permissions
Description
Users
[Document users that will need to be setup for each environment.]
User
Role
Client Identification and Authentication
[Explain if client identification or authentication is required. If so how will clients present their credentials to
AppServices? Where will the credentials stored? How will they get revoked if required?]
User Identification and Authentication
[Explain if user identification or authentication is required. If so how will users present their credentials to
AppServices? Where will the credentials stored? How will they get revoked if required?]
Collections
[List the collections that are required for this solution.]
Collection
Purpose
©2013 Apigee. All Rights Reserved.
Entities
[List the entities that are required for this solution.]
Entity
Purpose
Developer Portal Requirements
Branding
[Describe the branding requirements for the portal, e.g. color scheme, logo, images, font styles, header look &
feel, special formatting for certain elements like tables, any hyperlinks pointing to customer sites.]
Security
[Describe what portions of the portal are secure and unsecure. What type of security mechanism should be
implemented, e.g. forms authentication, IP whitelisting, etc.]
API Console
[Describe who is responsible for setting up, maintaining API Console. Describe WADL generation process and
how to update API Console with WADL.]
API Documentation
[Describe how API documentation will be created and uploaded into the portal. Explain whether customer
requires more than one portal deployed, i.e. staging and production. Explain the process of pushing content from
staging instance to production instance.]
Developer and Application Statistics
[Explain developer and application level statistics that are displayed within the portal.]
Browser Support
[Describe which browsers should be supported for this solution in minimum.]
Onboarding
Application Onboarding
[Describe the process of application onboarding for this solution, specifically:

Application registration process

Registration approval process

Application definition

Any legal points, e.g. payment
]
Developer Onboarding
[Describe the process of developer onboarding this solution, specifically:

Developer registration process

Developer registration approval process

Developer definition

Any legal points, e.g. payment
]
©2013 Apigee. All Rights Reserved.
Support
Operational Monitoring Requirements
Apigee Only Health check
[Describe the approach to monitor Apigee in isolation, e.g. /ping resource deployed in Apigee that doesn’t hit the
target but responds with a 200 ‘pong’ response.]
Target Only Health check
[Describe the approach to monitor target system(s) in isolation, e.g. /hello resource deployed in Apigee that calls
/hello resource exposed in the target that returns ‘hello’ back.]
Complete API Health check
[Describe the approach and document resources to be used to monitor API - passing through Apigee, hitting
target backend and returning back. This is preferably a real API resource that is not very demanding on the
resources.]
Maintenance Expectations
[Include information about how and when system maintenance windows will be made available to support Apigee
fix or scheduled maintenance deployment.]
©2013 Apigee. All Rights Reserved.
Testing Considerations
This chapter captures approach, expectations and considerations for functional and
performance testing of the overall implementation.
Functional Testing
Testing Approach
[What portions of functional testing will be implemented and executed by Apigee. What is the process of
approval/acceptance of functional tests implemented by Apigee?]
[What portions of functional testing will be implemented and executed by customer?]
[Which tools are used to do functional testing?]
Test Cases
[Document test cases and scenarios in scope for Apigee.]
Performance Testing
Testing Approach
[What portions of performance testing will be implemented and executed by Apigee. What is the process of
approval/acceptance of performance tests implemented by Apigee?]
[What portions of performance testing will be implemented and executed by customer?]
[Which tools will be used to execute performance tests?]
[What are the success criteria of performance tests?]
Test Cases
[Document test cases and scenarios in scope for Apigee.]
©2013 Apigee. All Rights Reserved.
Software Maintenance Considerations
System Maintenance
[Explain how will patches, upgrades be applied/deployed to Apigee products that are used in this solution. If this
is on-premise, briefly explain the process of getting approval and obtaining access to the system to perform such
upgrades and maintenance.]
©2013 Apigee. All Rights Reserved.
Training
[Discuss any specific customer requirements/needs for training for Apigee products to be used in this solution.]
©2013 Apigee. All Rights Reserved.