Edge REST Design Fundamentals

What isn't API Versioning?

It is NOT an indicator of the current release version.
Consumers don't care what your internal software release is. This information doesn't help a consumer build or maintain APIs

What IS API Versioning? Versioning is how you communicate when existing software is likely to break because of an update. Versioning only needs to happen when new required fields are added to queries, OR previously available data are removed from payloads


The Implications
 ● Versioning happens infrequently
 ● Versioning is a very impactful change, and may cause breakage of software that you were unaware even existed
 ● Communications about versioning should be proactive and complete

Best Practice: Avoid making breaking changes. Changes made to an API that will cause downstream breakage will reduce the utility of your API. Reduction in utility will reduce usage and increase time to market, as well as increase the cost associated with updates. Reduction in utility will also reduce use, which impacts value directly when clients pay for usage or indirectly when the organization can't easily leverage the solution.

Pick something and be consistent! Consistency leads to predictability. Predictability leads to intuitive usability. Usability leads to usage. Usage leads to innovation

Edge REST Design Fundamentals

What is REST?

REST is an acronym for "Representational State Transfer".
REST is a mechanism for using standard HTTP concepts to access machine readable resources. REST allows programmers to access web APIs with very little overhead.
A well-written REST API is easily understandable, readily consumable and self-documenting.


What does REST look like?
 ● Resource-Oriented
 ○ /v1/customers - a collection of or search for customers
 ○ /v1/customers/{} - a specific customer
 ● HTTP Verb Driven
 ○ GET - fetch / search
 ○ POST - create
 ○ PUT/PATCH - update
 ○ DELETE - remove


Why REST?
 ● Well understood in the industry
 ● Easily implementable
 ● Easily consumable
 ● Lifecycle tools
 ● Governance tools


Benefits of Resource-Oriented, Verb-Driven APIs
 ● Clear intent, common understanding
 ● HTTP caching tricks enabled ○ ETag ○ If-Modified-Since ○ Cache-Control
 ● Security, Logging, Analytics & more orthogonal to protoco


PUT vs PATCH
 ● Both verbs update an existing entity
 ● PATCH should change only mentioned fields, and null should remove a field
 ● PUT should completely replace the entity with provided payload

Best Practice: Sweep Complexity Behind the ' ? ' Relationships can be complex. Use query parameters instead of complex pathing.
 ● Which would you rather use?
 ● Which is more performant in bandwidth and compute constrained client environments?



Response codes should communicate only what the developer consuming an API needs It's not uncommon for a response code or message to accidentally divulge proprietary details from internal systems. Remember that response codes will be consumed by untrusted actors, and should communicate only what the developer needs to know to either correct the issue or alert the user, but no more.


Seven Minimal Error Codes
 ● 200
 ● 201
 ● 304
 ● 400
 ● 401
 ● 404
 ● 500


Seven Minimal Error Codes

 ● 200 OK Resource found, accessible and available. Action taken and response in payload.
 ● 201 Created Resource was created; payload contains new object (or reference to).
 ● 304 Not Modified No change since last request. Use cached copy.
 ● 400 Bad Request Request was missing required elements. Repair and resubmit.
 ● 401 Unauthorized User has not obtained any token. Include authorization instructions in return      body.
 ● 404 Not Found No such resource accessible to current client / user.

When should pagination be used?

When to use pagination:
● A large number of results in a list.
● An unknown number of results in a list.
● Results are of the same resource type.
● Queries or listings.


When not to use pagination:
 ● When the payload is not a list of objects.
 ● Small, known number of results never to exceed a handful (e.g. 5-10)
 ● 500 Server Error Something went wrong behind

Best Practice for Pagination.

Paged resources should have a metadata section that describes, at a minimum, the current page, the number of resources requested, and the number of resources in the current page listing.

A Helpful Idea Include a URL for the next/previous page, so the developer intuitively knows how to fetch them

Best Practice for Pagination. The item list need not be the full item. Instead, consider what summary information is required for use & display. Include that, plus a link to the full item. 

Apigee – Scalability

Edge – Capabilities 4 Edge is comprised of several stateless components that use infrastructure services to persist data: ● Gateway: Routing and API calls processing. ● UIs: Enterprise UI, Developer Portal. ● Infrastructure Services: Persistence of runtime, analytics and management. ● Management Server: Provides REST API for all configuration and management tasks. Note: Monetization, not shown in the diagram below, is part of Developer Services and leverages Gateway, Analytics Services and Management Server


Edge – Scalability 5 ● Management Server, Analytics Backend and Developer Portal can also be set up for high availability (HA). Multiples instances of these capabilities within a single zone or across zones is possible. ● Gateway, Infrastructure services, analytics and other capabilities can scale-out independently from each other


Edge – Scalability 6 ● Multi-DC and DR scalability. ● Edge is capable of scaling across multiple DCs/Regions in a active/active fashion. ● Active data replication between sites using eventual consistency

Edge – Component View 8 Each box represents a process. These processes can be can be run on independent of each other or co-located across a limited number of VM/servers.

Edge - Technology Stack 9 Edge components are, in general, Java based. Most components are based on a homegrown technology stack that leverages best in class open source technology under it. Below we highlight some of the underlying technologies used as building blocks.

Scaling by capability 10 ● Given the responsibility and capabilities offered by each component, scalability requirements and how they are implemented may vary. ● In most scenarios, scaling to accommodate higher API volume may impact only components serving live API traffic. ● Analytics data components may have to be scaled in response to increased API traffic and/or raw analytics data retention policy. ● Other components may grow in number mostly driven by high availability requirements for those capabilities


Multitenancy
Planets represent an entire physical installation and it can encompass multiple regions and pods.
Regional Services are shared by many pods across a single geographical region and maintain state and provide an API that works across the pods in a region. Pods are a collection of servers that share logical functions such as a Gateway Pod or an Analytics Pod. Orgs provide logical grouping to secure access to API management services. Orgs are associated with pods for servers – they can either share hardware or be isolated. Environments are virtual routes that allow API bundles to be deployed and tested within and Org. Environments can be associated with pods for servers independently of the Org. Virtual Hosts are similar to Apache Virtual hosts and route traffic to environments based on ports and domain names. Planet P 

API Proxy and Target Endpoints

 • Define an API as a series of resources that access a given target system.

 • Client-side interfaces can be accessed using either HTTP or HTTPS

• Targets can be accessed using either HTTP or HTTPS, using either one-way SSL or two-way SSL with mutual authentication

 • REST and SOAP targets supported

 • “First match” selection: define a set of resource criteria matching incoming requests, and the first match found controls request execution

• Resource matching on path nodes, query parameters, HTTP verbs and other types of conditions

• Determine target service for requests using either static or dynamic routing with route rules defined in the proxy endpoint

Variables and Conditions
• Variables allow you to store data for use during policy execution – Create using the Assign Message policy or from JavaScript/Java policies – Edge provides an extensive set of predefined variables covering areas such as:

• System (date/time, hostname, etc.)

• Configuration (organization/environment/application name, proxy base path, etc.)

• Request and response (client IP address, query and form parameters, headers, request body, target hostname, timing data, etc.)

• Policy (variables specific to the individual policy, such as rate limit info)

• OAuth 1.0a and 2.0 (information related to access tokens, etc.)

• Conditions allow you to control when a policy gets executed and which of a number of resource definitions is selected for processing – Compare path nodes, HTTP verbs, headers, query parameters, form parameters or variables with each other


Controlling Edge using Management APIs • Create, manage and delete just about anything: – API proxies – Policies – Developers and companies – Apps, app families and app keys – API products – Environments • Export and import entities • Manage users within org

What does it mean to “develop with Edge Platform”? • Determine the best organization and environment configuration for your needs • Identify members of the API team that need Edge access • Identify the authorization needs for the members • Design and implement mechanisms for registering/approving Developers / Apps, providing access to documentation and other resources • Produce general guidelines for grouping your APIs into Products • Produce general guidelines for grouping your backend resources into Proxy Bundles • Identify deployment, Management and Monitoring strategies • Create API design, testing, access control and source code management guidelines • Design and document your Proxies identifying common policy flow or common proxies • Define test cases that verify the functionality, performance and load-bearing capacity of your APIs • Define process and procedure for moving proxy bundles between environments • Implement, Test and Deploy your APIs • Monitor the adoption and operation of your APIs


Lab 01

- Getting Setup • Using a web browser Navigate to https://login.apigee.com/login • If you have an apigee account, login • If you do not have an apigee account, select “sign up” – Fill out form and select create account – Activate Account by selecting link in email • Could take 5 – 10 minutes • Under API Management select the “launch” or “activate” button • Welcome to Edge!!

Apigee Introduction

Key Terms

 • An Organization is a collection of users, APIs and other resources.

 • An Environment is a subset of APIs in an organization that are in a given deployment state – Default environments: test and prod

• An API Proxy is a set of configurable logic that handles API requests.

• Flows (sometimes called resources) represent a specific request type within an API proxy - usually qualified by verb and path, but often by other request parameters as well.

• Policies (also known as Flow steps) are bits of logic that can be executed during the course of processing a request – Policies can be applied to all resources in a proxy or only to select resources – Policies can be conditionally executed



Developers and Apps

• Developers are the internal or external partners that create applications that use your API products – can be internal or external, and generally represent individuals – can be grouped into Companies

• Developers are associated with Applications, which are developer-written programs that use APIs – can also be included in Companies

• Applications (and Flows) can be grouped into Products for exposure to Application Developers – Application Developers are restricted by Products NOTE: Companies, Company App Family, Company Developers can be configured using API. For configuring the above using UI, the org needs to enable monetization and some customization in the Developer Portal

API Security

API Products are: – collections of API resources, combined with a service plan and presented to developers as a bundle – the central mechanism for authorization and access control Consumer Keys are: – assigned to an application when it is created – linked to a product when the product is associated with an application Product API Proxy 1 API Proxy 2 API Proxy 3 Consumer Key Apps Developer NOTE: Consumer Key is also known as Client ID and API Key



Security for Edge Users Organization Administrator

• Administrator of an organization
• Responsible for mainly user management but has super access to everything Business User

• API Program Manager
 • Responsible for success of API program and developer management, KPIs Operations Administrator

 • API Operation Manager
• Responsible for production and test deployment, troubleshooting User

• API Developer
• Responsible for development of API proxy, policy management, troubleshooting etc.
 • Permissions define create/read/update/delete access to resources
• Roles identify a collection of permissions that can be assigned to a user
• Predefined roles assign common permissions to key Edge resources