Submitted by steven.maglio@… on

Architectural Overview

Products

The Apigee suite of tools is broken into three major products Those products are broken down into components which are shared between the products.

  • Apigee Gateway

    This is the actual proxy server which recieves requests from the users of the APIs. It has no UI frontend itself. Instead it is managed through the Gateway Management product. It hosts the dev, test, and prod endpoints: api.ucsb.edu, test.api.ucsb.edu, dev.api.ucsb.edu.
     

  • Gateway Management (Edge)

    This is the Admin Portal for the Apigee Gateway. Within here are the API Endpoints, the API Security, and the Developer & Application Registry. The Apigee Gateway is configured within the Gateway Management portal and it manages sending out and coordinating updates to the Apigee Gateway. It can be used to manage Developer and Application accounts, but mostly rely's on the Developer Portal to handle those operations.

    The Gaetway Management Portal also contains two keys features. The Tracing Tool used to debug problems within the Apigee Gateway and the Reporting Tool. There is a REST API that can be used to automate much of the functionality provided by the Gateway Management Portal.
     

  • Developer Portal (developer.ucsb.edu)

    The Developer Portal is the entry point for Developers to test out and gain access to APIs. It is the public face of the API Gateway, as such it contains the Documentation and the API Testing features. It also the point where Developers create accounts, Developers creation Applications, and Applications request access to API Products.

 

Components

The products work together by using a shared components to communicate the desired configuration.

  • Developers
    • A developer is expected to be created within the Developer Portal. When an Account is created within a developer portal it creates a new Developer in the Gateway Management Portal. Each Developer Portal instance (Dev, Test, Prod) is isolated from each other. So, an Account created in Prod will not appear in Dev. However, the Developer (Gateway Management Portal) that is created is available for use in all environments. When an Account is created, is not immediately Active. Instead, the account needs to be set to Active in the Developer Portal. Once an Account is set to Active, the associated Developer is then Approved.
  • Applications
    • After an Account (Developer) is approved in the Developer Portal, then it can create Applications. Applications are critical to be created because they are the component that's actually given access to an API. Developers aren't given access to APIs, only Applications. This allows the system to define granual permissions for each application. Rather than a massive set of permissions for a Developer.
  • API Products
    • An Application must request Access to an API Product. Within the Developer Portal API Products are meant to appear as if they are the APIs. But, they are an abstraction above APIs. API Products are what actually control permissions and access, so it's the appropriate component to request access through.
    • The Developer Portal can't approve access for to an API Product, that is done in the Gateway Management Portal. It's also possible approve/deny access throught the REST Management API. We use automated tooling to grant auto-approval on a few select API Products.
    • API Products are also used to define specific configurations like rate limiting, granualar permissions for write vs read access, and special attribute configuration.
    • API Products are designed to be incredibly flexible. They can be used to define very standard configurations, like access to unrestricted endpoints like Students Lookups. An API Product like that is based around access to a single API and can be given freely to many applications. On the opposite end of the spectrum an API Product can be built specifically for a single Application. For example, if Salesforce needed access to a particular set of Admissions data. An API Product could be specifically setup that only gives their application access to exactly the API methods (methods are smaller than API endpoints) that it requires and nothing more.
  • API Proxies
    • Are the actual API Endpoints that will be deployed to the Apigee Gateway. These are what most people think of when they think of an "API". These are generally setup to correspond to a single resource provided by a backend API Provider. API Providers aren't listed or managed within the components. They are however an attribute of each API Proxy, because the API Proxies need to know where to get data from.
    • The API Endpoints are defined in a special Development tool provided within the Gateway Management Portal. It is based on XML configuration and is highly configurable to do be very flexible for your needs. Because of the depth and variety of things it can do, it's not a simple tool to learn. However ...
    • The API Proxies come with a Tracing Tool. This is the most important feature in the Gateway Management Portal. It can be used to debug the API Endpoints and help figure out whats working correctly and what's going wrong with your API Proxies. Beacuse sure to use the javascript debugging features to detailed information about your API Endpoints internal workings when your debugging with the Tracing Tool.
    • Finally, the API Proxies are deployed out to the Apigee Gateway. The Apigee Gateway is the proxy server which recieve the incoming requests, evaluates authentication/authorization, and performs internal operations before sending requests to the backend API Provider servers.
  • API Spec
    • These is an internal registry of Swagger documents which describe the backend API Provider interfaces. It's really only used for convience to help regenerate API Proxy endpoints, but it doesn't really have an extended usage throughout the system.