3 Replies Latest reply on Oct 16, 2013 8:16 AM by Eric Wittmann

    API Management: Core Concepts/Entities

    Eric Wittmann Apprentice

      Introduction

      This discussion is intended to hash out the core ideas/concepts/entities for the Overlord API Management project.  The intent is to start with just the core, required entities and expand out from there as needed.  For any API Management requirement we should be able to understand which concepts/entities are impacted/relevant.

       

      Components

      First, the API Management project is broken up into two core backend components:

       

      API Management

      This component allows users of the API Manager webapp to create and manage Applications and Services/APIs (see below).  This is the management component, it does not expose any API endpoints or govern any API requests.

       

      Gateway

      This component is the "runtime" piece of API Management - it is responsible for exposing physical API endpoints that client applications will invoke.  These API endpoints are governed by Policies configured by the users of the API Management component when the Services/APIs were created and configured.  This component is intended to be a high performance system designed to allow high throughput (low overhead) of inbound API requests.

       

      Entities

      When managing APIs and the applications that invoke those APIs, the following entities are useful (note that "Service" and "API" are synonymous):

       

      Organization - the top level structure used to group together Applications and Services with the set of users who are allowed to manage them.  Important: this does not enable any sort of relationship between an Application and a Service it might wish to invoke.  Instead, an Organization that contained both Applications and Services simply implies that a particular group of people (an Organization) is managing both a set of Services that can potentially be consumed some Application as well as one or more Application that itself will potentially consume some Services.  In other words, a single Organization may be developing both a set of Services and zero or more Applications - though these may not, in fact, be related to each other.

       

      User - represents someone who can log into the API Manager web application in order to manage Applications, Services, or both.  Users can be members of zero or more Organizations, allowing groups of users to jointly manage Applications and Services.

       

      Application - exists within an Organization and represents a client app which would like to invoke zero or more Services exposed by either the same Organization or some other Organization.  When first created, the Application does not have the ability to invoke any of the managed Services.

       

      Service - represents an API being exposed by some external back-end system, for which we would like to introduce governance/management capabilities.  Services also exist within an Organization.

       

      Plan - another entity that exists within an Organization, a Plan represents a Service Tier for a Service or group of Services.  When an Application requires access to a Service, it must connect with that Service through a Plan.

       

      Contract - when an Application requires access to a Service (i.e. permission to invoke a Service) it must make a connect with/reference to that Service by creating a Contract with it.  The Contract is a connection between an Application and a Service via a Plan.

       

      Policy - the backbone of Gateway functionality, Policies are executed every time a client application invokes a physical endpoint exposed by the Gateway.  Policies can be configured in three places:

      • Application
      • Service
      • Plan

      When the Gateway endpoint is invoked a Policy Chain is created by aggregating the Policies configured at each of the above levels.  This Policy Chain is then executed in sequence starting with the inbound Request and ending with the API response.

       

      APIManager-CoreEntities.png

       

      Message was edited by: Eric Wittmann (fixed copy/paste error in diagram)

        • 1. Re: API Management: Core Concepts/Entities
          Gary Brown Master

          Eric Wittmann wrote:

           

          User - represents someone who can log into the API Manager web application in order to manage Applications, Services, or both.  Users can be members of zero or more Organizations, allowing groups of users to jointly manage Applications and Services

           

          Using the github analogy, I guess some users would also be administrators within the organization, having the ability to assign roles to the other users? Although there would also need to be automated ways for developers to sign up to an organization - but that could be a configuration option setup by the admin on the organization (i.e. enable dev to join and create apps). I think users with the ability to add/advertise services within the organization would need to be explicitly added by the admin user.

           

          Eric Wittmann wrote:

           

          Application - exists within an Organization and represents a client app which would like to invoke zero or more Services exposed by either the same Organization or some other Organization.  When first created, the Application does not have the ability to invoke any of the managed Services.

           

           

          In the prototype there was the ability for applications to use services (essentially within the same organization) without any explicit link, if the service had no 'plans' associated with it (and therefore was not restricted). I think this is a useful capability, as there may be some utility services that are of general use.

           

          The pro to this approach is that it requires less provisioning to enable the app to use a set of 'public' services in the org. The con is that it can be useful to have explicit information about the relationship between the apps and the services that are using - e.g. impact analysis.

           

          Maybe this is something that should be a configuration option on the org - i.e. whether services with no plan are implicitly visible to all apps in the org?

           

          Eric Wittmann wrote:

          Plan - another entity that exists within an Organization, a Plan represents a Service Tier for a Service or group of Services.  When an Application requires access to a Service, it must connect with that Service through a Plan.

           

          Just to clarify - the Plan represents a Service Level Agreement. So a service may offer multiple different plans, e.g. Gold, Silver, etc, offering different levels of services to the consuming applications. Although not directly relevant in this doc, as it is only discussing the concepts, we need to consider what mechanisms will be used to support an application owner (developer) requesting a particular plan for a service, and the supporting financial transaction that may follow.

           

          In the model diagram, the plan has some properties that look like a copy/paste error - as the plan is not related to the endpoint?

          • 2. Re: API Management: Core Concepts/Entities
            Eric Wittmann Apprentice

            Yes, Users will be members of Organizations and would presumably have roles within those Organizations.  Suggestions for Roles include:

             

            • Administrator - grants full access to the Org, including adding Members
            • Service Manager - grants the ability to manage the APIs/Services within the Org
            • Application Developer - grants the ability to manage the Org's Applications

             

            I can imagine other roles as well, which might grant various subsets of the general functionality above.

            • 3. Re: API Management: Core Concepts/Entities
              Eric Wittmann Apprentice

              Regarding explicit vs. implicit Contracts (links between Applications and Services):  yes I was assuming that the value of having an explicit link between an Application and every Service it consumes (even if that Services has no Plans and is thus public) outweighed the overhead of maintaining those links.  I may be wrong and/or we may need to support both.