functional and non-functional requirements · web viewthis document is to capture the...

©2013 Apigee. All Rights Reserved.

[Client - Project Name]Functional & Non-Functional Requirements

[version]

[Author]


Purpose 1Introduction 1

About [Project Name] 1Project Objectives 1High Level Functional Description 1

Client-Side Requirements 3Apigee Clients 3Connectivity 3Security Requirements 3

Transport Security 3Application and User Identification and Authorization 3User Identity Validation 3Client IP Control 3

Target Requirements 4Apigee Targets 4Connectivity 4Load Balancing 4Security Requirements 4

Transport Security 4Apigee Identification and Authorization 4User Identity Forwarding 4IP Control 4

Data Security 4PCI Requirement 4

Operational Requirements 5Datacenter/Region Requirements 5Failover Requirements 5Client-Side Load Balancing Requirements 5Availability Expectations 5

Organizations and Environments 5API Development and Deployment Process 5

Performance 6Performance Expectations 6

Target Response Times 6Target Throughput 6Apigee Response Times 6Apigee Throughput 6


Solution Requirements 7API Requirements 7

Traffic Management 7Security 7Mediation 7

Analytics Requirements 7Custom Reports 7Custom Variables 8Data Retention and Archival Strategy 8Custom Data Extraction 8

AppServices Requirements 8Organizational Structure 8Data Import Requirements 8Data Export Requirements 8Security 8Collections 8Entities 9

Developer Portal Requirements 9Branding 9Security 9API Console 9API Documentation 9Developer and Application Statistics 9Browser Support 9

Onboarding 9Application Onboarding 9Developer Onboarding 9

Support 10Operational Monitoring Requirements 10

Apigee Only Health check 10Target Only Health check 10Complete API Health check 10

Maintenance Expectations 10Testing Considerations 11

Functional Testing 11Testing Approach 11Test Cases 11

Performance Testing 11Testing Approach 11Test Cases 11

Software Maintenance Considerations 12System Maintenance 12

Training 13


PurposeThis 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).

IntroductionThis 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


Developer Portal


AppServices



Client-Side RequirementsThis 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]


Target RequirementsThis 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 self-signed, 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.]

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 (on-premise).]

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.]


PerformanceThis 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.]


Solution RequirementsAPI Requirements[List the client-side API requirements and explain in detail, e.g.]

Requirement DetailsAPI Design [Who is responsible for the design of the API]API Implementation [Who is responsible for the implementation in Apigee layer]

Rate Limiting[Rates applied globally or based on request variable (like IP). How does customer want to maintain the rate setting]

Quotas[Quotas applied globally or based on request variable (like IP). How does customer want to maintain the quota allowance]

Caching [Which resources, approximate size, TTL, globally distributed, etc.]

Internationalization/Localization[Especially around data encoding (UTF-8) and languages to be supported for Apigee responses (traffic management, security, etc.)]

Traffic Management

Requirement Details

Rate Limiting[Rates applied globally or based on request variable (like IP). How does customer want to maintain the rate setting]

Quotas

[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?]

Caching[Which resources, approximate size, TTL, globally distributed, etc. Full response or partial?]

Security

Requirement DetailsThreat ProtectionRegular Expression ProtectionOAuthAPI KeysAccess Control [E.g. IP based, etc.]SAML AssertionAttack Notification ProtectionReaction Against AttackersData Security

Mediation

Requirement DetailsJSON to XMLXML to JSONXSL TransformSOAP Message ValidationKey Value MapService 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.]

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

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

]


SupportOperational 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.]


Testing ConsiderationsThis 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.]


Software Maintenance ConsiderationsSystem 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.]


Training[Discuss any specific customer requirements/needs for training for Apigee products to be used in this solution.]

functional and non-functional requirements · web viewthis document is to capture the...

Documents