The focus of this chapter is to provide a comprehensive yet detailed overview of the Oracle API Platform Cloud Service (APIP CS) architecture. The chapter starts off by providing a high-level view and explanation of the architectural components that build up the platform, continues by describing the different personas and roles that can interact with the platform, and finalizes by providing a sample implementation architecture.
In this chapter, you will find:
- A walk-through platform evolution into 3rd generation
- An overview of the Oracle API Platform
- A look at the platform architecture
- An introduction to Apiary
- The management service APIs
- Introduction to API plans
The Oracle API Platform Cloud Service is a 3rd generation API management platform (refer to the Preface for further context) built almost entirely from the ground up to satisfy modern integration requirements such as real-time access to information via REST APIs.
As its name suggests, the platform is a cloud-based Platform as a Service (PaaS), meaning that it can be purchased in a subscription-based model, metered or non-metered.
The platform supports the full life cycle of API management, from API design (using Apiary, which is described later in the chapter) to continuous integration, implementation, promotion, operations, and decommissioning/retirement.
Please refer to the Oracle API Platform Cloud Service home page for further informationÂ https://cloud.oracle.com/en_US/api-platform.
3rd generation API management platforms
The platform is fully hybrid meaning that it can be deployed in cloud computing but also on-premises. It's lightweight and equally well suited for Microservices Architecture, in other words, 3rd generation.
A recommended read would beÂ 3rd Generation API platforms: from proxies to micro gatewaysÂ http://www.oracle.com/technetwork/articles/soa/weir-3rd-gen-api-mgmt-3787102.html.
But what exactly is a 3rd generation API Platform in the context of Oracle product offering?
This concept is better understood by understanding the chronological evolution of Oracle's API offering throughout time.
In the following section it is described how Oracle's offering evolved from an Enterprise Service Bus centric architecture, to then becoming a SOA/SCA feature-rich (monolithic) platform, and then evolving into an architecture that is distributed, lighter weight, and therefore, suitable for hybrid and microservices architectures.
The following presentation is recommended as it provides a good overview as to how SOA is related to Microservices, and what Microservices actually are:Â https://www.slideshare.net/capgemini/microservices-and-soa
As described in the Preface of this book, APIs are not really new. What is new is how we refer to them in the context of the web architectures and the standards/technologies/protocols used to deliver them. For this reason, when looking back through time, one must also look at traditional integration platforms such as Enterprise Service Bus (ESB).
For example, Oracle's first ESB offering was part of the very first release of Oracle SOA Suite (10g) launched mid/late 2006. This ESB centric architecture, offered support for SOAP/WSDL-based APIs that at the time we referred to as web services. It also offered support for emerging standards such as Business Process Execution Language (BPEL) with BPEL Process Manager, WS-* standards such as WS-Security with Web Services Manager (WSM), business rules with the Rules Engine (also known asÂ Rules Author) and real-time business dashboards with Business Activity Monitoring (BAM).
This ESB and open-standards centric architecture delivered the initial capabilities for XML-based APIs. This is why it is referred to in the diagram as Generation Zero. In other words, the starting point:
Oracle's Generation Zero API platform
It is worth mentioning that some of the reasons SOA had become so popular industry-wide are because it promised to deliver countless business benefits, most notably, it promised to close the gap between business and IT with the adoption of languages such as BPEL that in theory would make it easier for business people to define processes that could later be executed, reduce of IT spending by re-using existing assets exposed as web services, increased business agility by providing an architecture that was easier to change and evolve, and better visibility and insight over how and when business assets were used and reused and how processes were executed.
Oracle SOA Suite 11g, released around 2008, was an important milestone for Oracle and it enjoyed vast community support and wide-spread industry adoption. The product was the result of the merge of SOA Suite 10g with the then recently acquired BEA Aqualogic offering. It was (and still is) feature-rich and many used it as a one-stop-shop to deliver SOA and requirements around it:
Oracle's 1st generation API platform
An important characteristic of 1st generation is the appearance of what was referred at the time as XML Gateways. The main purpose of such Gateways was to act as a Security Proxy to SOAP Web Services in Demilitarized Zones (DMZ) so when exposed to untrusted or insecure networks (for example, the internet), the Web Service would have an additional layer of security. Some of the capabilities introduced by such gateways were SSL termination, WS-Security and protection against major treats such as the ones mentioned in the Open Web Application Security Project (OWASP) Top 10. Although at this time Oracle did not offer a specific solution for this, the industry saw the likes of Vordel (later acquired by Axway), DataPower (later acquired by IBM), and Layer 7 (later acquired by CA) emerging as leaders in this space.
As the adoption of SOA proliferated across organizations of every size, almost in parallel the popularity of smartphones and mobile apps rocketed, to the point of becoming an essential part of everyone's everyday life. From this point forward, mobile apps became a vehicle for organizations to not just more intimately engage customers, but also to introduce mobility to the workforce which would in turn optimize processes and increase productivity.
It's worth noting that the popularity of smartphones really started with the launch of Apple's first iPhone back in 2007. Although the concept of apps wasn't really new (specially in Linux communities), the iPhone made it a marketing session and mobile apps became the new session.
As communities of mobile developers grew exponentially around the globe, a common trend started to emerged. When it came to delivering access to backend enterprise information assets, majority of mobile developers favored Roy Fielding's REpresentational State Transfer (REST) architectural style to implement APIs over the technologies and protocols commonly used in traditional SOA architectures (for example, XML/SOAP web services).
By many, web services and standards around it had perhaps become too complicated, both to understand and implement, and therefore, a simpler way of implementing APIs was well received, not just by mobile developers, but eventually also by application developers and SOA practitioners as well. Needless to say, the popularity of SOAP-based web services started to decline, and the use of REST APIs became prevalent.
Perhaps because of the obvious similarities of API Gateways to ESBs and also XML Gateways, majority vendors opted to adjust their existing (1stÂ generation) offerings.
2nd generation API platforms are therefore nothing but (1st generation) ESBs and/or XML Gateways that had been extended and/or enhanced in support of rich REST APIs capabilities and the life cycle management of API, disciplined later known as API management.
- Oracle API Catalog 12c, an adaptation (simplification) of Oracle Enterprise Repository (OER) to support the harvesting and cataloging of REST APIs
- Oracle's API Manager 12c, an extension to Oracle Service Bus (OSB) to support management capabilities of REST endpoints
- Oracle API Gateway 11g, an OEM of Axway's (former Vordel's) XML Gateway which was adapted/extended to support REST and JSON payloads
More on this in Chapter 10,Moving from API Management 12c to APIP CS.
Oracle's 2nd generation API platform
Although 2nd generation API Platforms did provide some of the answers many customers were after, they also had a major pitfall. As they are in effect the result of additional layers of capabilities and extensions added to an existing (perhaps already complicated) stack, instead of delivering the simplicity that made the REST architectural style so popular, the entire process of installing/configuring the platform plus building, deploying and managing APIs on top tended to be very complicated, to say the least.
During this same period, Cloud Computing had also become a serious choice for large organizations to run their workloads. This meant that information assets were no longer to be available in on-premise data centers, but also in a vendor's cloud (and not necessarily Oracle's). Because of this, capabilities to being able to also implement APIs in the cloud were also expected of a vendor's API Platform.
As if this wasn't enough, the rise of Microservices Architectures as a more flexible, highly scalable, and alternative way to implement APIs and realize SOA meant that traditional 2nd generation platforms seriously struggled to keep up with the pace of change and thus, meet the expectations of customers â many of which had already been exposed to a degree to all these new technology trends.
3rd generation API Platform are therefore born not as enhancement or extension of previous offerings, but rather built to a very large extend from the ground up to satisfy modern architectural requirements souring REST/Web APIs, microservices architectures and hybrid landscapes where information is distributed among systems deployed in the cloud (and not just one, but multiple clouds) and on-premise data centers:
Oracle's 3rd generation API platform
That said, Oracle API Platform Cloud Service was launched early 2017 as a strong response to the industry demands and as a flagship product for API Management in general. The offering aligns perfectly well with the concept of 3rd generation API Platforms not just because of its hybrid capabilities, but also because of its flexible and scalable architecture which makes it suitable for use not just in traditional SOA landscapes, but also modern Microservices Architectures, both on-premise or cloud.
The platform, built almost entirely from the ground up, does not have any relation with Oracle's previous (2nd generation) API offering as it is much simpler, lighter weight, and scalable. The following chapter describes this in more detail.
Oracle APIP CS â high-level architecture
As the diagram suggests, the platform consists the following components:
- Management Service: The management service is a cloud-based application that underpins the management console, developer portal, and platform API. It's the engine of the entire platform, in other words, the brains of the platform.
- Management Portal: As the name suggests, this is where APIs, Gateways and User/Roles are managed. It's a role-based application so what a user can do pretty much depends on the role the user belongs to.
- Developer Portal: A web-based application where developers can search and subscribe to APIs. This is where all of the API documentation can be found and also where application keys are provided after a subscription to an API takes place.
- REST APIs: Oracle APIP CS was built following an API-first approach and therefore, all functionality available via the different portals are also accessible via the REST endpoints. In fact, more capabilities are available via the API than available than from the portalsâat least in the first release of the product.
- Apiary: This is the component of the platform responsible for delivering API-first design capabilities and enables a documentation-driven API design approach. Apiary in itself is feature-rich delivering capabilities such as support for Swagger and API Blueprint specifications, a mockup engine that allows automatic stubs generation based on a API specification, assertions engine for team-based semantic validation, team collaboration, among many others, which will be described in the next section. It is also worth noting that both the management console and the developer portal have already been integrated with Apiary.
- API Gateways: These are the engines that enforce/apply the different API policies to the managed endpoints. They can be deployed virtually in any computing infrastructure, cloud and/or on-premises, so long that the right (certified) operating system is used. Gateways communicate with the management service implementing a featured known as phone-home. The way it works is that the gateways are configured to periodically call the Oracle API-CS platform API to download new policies that are to be applied to the specified APIs and also download platform updates that need to be applied to the gateway infrastructure. In this model, it is the gateways responsibility to establish the communication to the management service and not the other way around, therefore making it a lot easier to deploy gateways as no firewall ports or network changes are required-so long that the gateways have outbound internet access.
- Identity Cloud Service: Although this component is not really part of the Oracle APIP CS, but rather a related cloud service, it's important to depict as it enables the platform to integrate with an organization's existing LDAP directory. Given that the majority of organizations may already have an LDAP directory of some sort (that is, MS Active Directory) to manage their users and roles, this capability becomes quite critical when implementing the platform in a landscape that has many users especially developers.
Note that in the very first release of Oracle APIP CS, the use of Identity Cloud Service is not supported. Instead, WebLogic Console is configured to in order to support
- Compute nodes, Oracle Traffic Director (OTD) and Database Cloud: All Management Services, including the Management and Developer Portals, run in Oracle cloud infrastructure. When the platform is set-up, these components are provisioned in 4 compute nodes: two for the management service and portals, one for the OTD load balancer and one for the database cloud instance. The creation of this IaaS infrastructure has to have happened prior the provisioning the Oracle APIP CS.
The following section elaborates each component in detail.
This section elaborates into detail each of the components of the management portal.
The management portal is the main console for the Oracle API platform. A web-based application deployed in the Oracle Cloud PaaS, it delivers capabilities to manage an API throughout the entire lifecycle. From API creation, policy implementation, access management, and API documentation to API documentation and analytics. In addition, depending on the user role (described later in the chapter), it is also possible to manage users, API gateways, and platform settings. The management portal comes with several features as illustrated in the following diagram:
Oracle APIP CS-management portal
The following section describes each of the pages illustrated in the diagram.
Note that the pages available in the management portal, depends on the version of the platforms being used. Versions have been appended to the page name to show from which release a given page is available. Nomenclature for versions are simple: <year>
.<release number>. For example, v17.x + indicates that a page is available from 2017 onwards including any quarter.
This book is based on version 17.3.3. (3rd quarter 2017). This chapter will be updated yearly to reflect the latest additions and key known features of the roadmap.
The APIs page is the landing page after a user has signed in into the management portal. The landing page is also an API catalog as all APIs created in the platform are initially listed here and can also be searched upon based on different criteria:
Management portalâAPIs page
It is also from this page that a user can either create a new API by clicking on
Create API or edit an existing by simply clicking on the name of a given API. This action will take the user into the
API implementation page:
Management portalâAPI implementation page
When it comes to API life cycle management, this is one of the most (if not the most) important pages as from here it is possible to implement an API by assigning and configuring any relevant policies, deploy it, create the API documentation, manage the user grants, application registrations, and also retrieve insightful API analytics.
Note that the
APIs page is overall targeted mainly at API Managers, which in API Platform is the role responsible for implementing an API. Roles and responsibilities are described in greater detail in section Roles later in the chapter.
The API implementation page's main purpose is to provide all capabilities needed in order to fully implement an API. For example, policy implementation, deployment, documentation, security, and monitoring are all capabilities provided within this page.
The page is divided into six different sections, each of which can be accessed by clicking on the relevant icons located on the right-hand side of the page.
An API policy is, in essence, a configurable rule that is enforced at runtime when the API is called. Policies come in many flavors and for different purposes. A mature API management offering should provide a variety of policies to ensure that several needs can be satisfied, such as authentication, authorization, key validation, throttling, and routing, to name a few.
The management portal comes with twenty-one predefined policies (at the time this book was written based on API Platform Cloud Service version 17.3.3), grouped in 5 main categories. Policies can be applied to request and response payloads in HTTP methods: GET, POST, PUT, and DELETE.
Refer to the following link for the latest list of available policies:https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html#GUID-99A486F8-6A5C-4E62-9E20-B641790509EA.
- Security: policies that focused on enforcing authentication, authorization, key validation, and other thread protection policies such as IP filtering and cross-origin resource sharing (CORS):
Implementation sectionâsecurity policies
- Traffic management: this group of policies deliver capabilities to throttle and limit the number of API calls made by consumers based on multiple criteria. In other words, handle the volume of traffic sent to the API. This type of policy can as well be useful to prevent against denial of service attacks (DoS). The following screenshot shows the
Traffic Managementpolicies as shown in the management portal:
Implementation sectionâtraffic management policies
Implementation sectionâinterface management policies
- Routing: Policies focused on routing HTTP calls to service endpoints based on multiple criteria such as HTTP header values, the specific gateway handling the traffic, the application calling the API or based on HTTP resource accessed. The following screenshot shows the
Routingpolicies as shown in the management portal:
Implementation sectionârouting policies
Implementation sectionâother policies
For an example on how to implement API policies refer to Chapter 6, Defining Policies for APIs. For further information on policies available in management portal and how to implement them, please refer to the following link:https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html#GUID-1EE65B88-5050-4AFE-8F53-4B256D4E2AA3
deployment section of the
API implementation page allows for the API to be deployed into any registered logicalÂ gateway. When an API is deployed to a given logical gateway, all gateway nodes will deploy the API. From this same section, it is possible to undeploy APIs and also visualize any rejected or failed API deployments:
In the management portal, all gateways nodes (instance of gateways running on a machine), are grouped into what's referred to as logical gateways. A logical gateway, therefore, encompassed all gateway nodes associated to the same logical instance. The concept of a logical gateway will be explained in more detail later in the chapter.
API implementation pageâdeployments section
- Â API overview documentation: Simply put, free text to help describe the functionality and usage of the API. It can be HTML or Markdown text.
- API specification documentation: The API Blueprint or Swagger specification document for the API created in Apiary:
API implementation pageâpublication section
APIs can be specified in a number of ways, as opposed to web services where the main mechanism to define a service is by creating a WSDL (web service description language) document. For APIs, the most popular specifications are Swagger and API Blueprint. Apiary supports both. Recommend reading the following article for further information on the topic:https://nordicapis.com/top-specification-formats-for-rest-apis
Grants section allows for different grants to be specified and therefore, control which users or groups can manage, deploy, register, and read private/public information for the API. There are six grants available:
Manage API: Allows to modify the definition of and issue grants for the API
View all details: Allows to view all information about the API in the management portal
Deploy API: Allows to deploy or un-deploy the API to a gateway for which they have deploy rights
View public details: Allows to view the publicly available details of this API on the Developer Portal
Register: Allows to users to register their applications to use the API
Request registration: Allows to users to request registration of their applications to use the API
API implementation pageâgrants section
Developers that can access the developer portal can create applications that are then registered to consume any given API they have been granted access to. When an application is registered to a given API, an application-key is provided. Presence of the application-key when calling an API can then be enforced by using the Key Validation policy.
From this page, registrations to the API can be created, approved, rejected, or suspended:
API implementation pageâregistration section
Analyticssection delivers insightful near-real dashboards and stats for the API. Information such as the total number of calls, successful versus failed calls, response times, and payload size can be visualized and filtered as well based on criteria such as gateways that processed the calls, name of the consumer application and timeframes.
In the section there are three main tabs:
General: this tab provides a summary of all API calls in a single dashboard. The calls are can be seen classified by volume and status (All, Successful, Rejected or Failed), payload size, or API resource.
Applications: this tab provides a summary view of API calls broken down by Applications. It provides a total of successful calls, rejections and errors.
Errors and Rejections: this tab provides great insight on API calls that resulted in
Errors(most likely a HTTP 5xx Server Error response code) or
Rejections(typically a HTTP 401 Unauthorized or 403 Forbidden). The calls can be seen classified by total numbers and type of error/rejection.
API implementation pageâanalytics section
The APIs page documentation can be accessed from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-apis.html
As it was briefly described earlier, an application in Oracle APIP CS represents the consumers for one or many APIs. For API-Platform an application is just a logical representation, therefore it does not matter what the application actually is. It can be a mobile application, a web application or even a wearable device.
Applications are uniquely identified with applications keys which can be visualized by clicking on the application itself and accessing the application details page:
Management portalâapplications page
Once in the application details page, the
Settings section is displayed. From here, it is possible not only to visualize the application key or
App Key for short, but also reissue it. This can be useful for security purposes. Other details such as contact details for the owner of the application and type of application (that is, mobile app, backend system, and so on) can be visualized:
Applications pageâapplication details
Application grants work in a similar to API grants (explained in the API section) however in the context of an application. The applications page documentation can be accessed from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-applications.html#GUID-F035A756-2934-40EB-8D03-1FC610E8FE5D
Gateways page, all registered logical gateways and gateways nodes can be visualized and managed. Details such as gatewayÂ names and description, load balancerURLs and number of APIs deployed are visible. Also, note that next to the gateway name the version of the gateway is visible. This is important to make sure that the version implemented is compatible with the version of the management service (ideally both should be in the same version):
Management portalâgateways page
A logical gateway as the name suggests, represents a grouping of one or many gateway nodes. A gateway node is an actual physical instance of the gateway that's running on a compute instance (could be in the cloud and/or on-premise) and is capable of handling API requests.
Logical gateways and gateway nodes
By clicking on a given gateway listed, the
Gateway details page opens, and from there gatewayÂ settings, gateway properties, physical gateway nodes belonging to the logical gateway, deployments, grants, and gateway analytics can be visualized and certain properties edited.
The settings section (landing section), provides details such as the load balancer URL, the unique logical
Gateway ID, and the gateway location which is just free text metadata to provide further insight as to where the actual gateway is actually deployed:
Gateways pageâsettings section
Properties section allows for certain message processing limits to be defined. This is important as common question asked when implementing a gateway is what is the maximum message size that can be handled, so such details cannot just be visualized but also edited from this page.
Following is the description as per Oracle documentation:
Maximum Message Size: Specifies the maximum size, in bytes, of the request, excluding attachments. The default value is set to 1024000. The maximum allowed value is 200 MB.
Maximum Number of Unbounded Items: Specifies the maximum number of unbounded items that a message can contain. The default value is set to 1024.
Maximum Size of a Single Message Entry: Specifies the maximum size of a single message entity, such as an element, attribute or comment. The default value is 102400.
Maximum Nested Elements in a Message: Specifies the maximum number of nested elements allowed in a message. The default value is 1024 nested elements.
Gateways pageâgateway properties section
NodesÂ section, details of all physical nodes (in other words running gateway instances) that belong to the logical gateway can be visualized. From this page, details of the physical host URL where the gateways are running are visible. If the host URLs are to be accessed via HTTP proxies, the proxies' URLs can be specified from this page.
Of special interest, is the polling intervals information which is available on the top-right-hand side of the section.
This information is important as it informs how often gateways are supposed to phone-home and when was the last time it occurred. When troubleshooting, this is an important page to look at.
Gateways pageânodes section
Deployments section page lists APIs that have been deployed to the logical gateway. The page is equivalent to the API deployments section; however, all APIs deployed to the logical gateway are listed as opposed to a single API. Therefore, it is a useful page if actions are required in more than one API (that is, undeploying more than one API):
Gateways pageâdeployments section
Grants section works in a similar way to the API grants section but in the context of the logical gateway. Of special interest is that grants specific to system users for the operation of the logical gateway (node service accounts) and also deployment grants to the logical gateway, can be managed from this page. Especially the deployment grants management for a logical gateway can be very useful as users can be granted rights to deploy APIs to a logical gateway as opposed to of providing grants on an API by API basis:
Gateways pageâgrants section
Analytics pages are similar to the API analytics page in the way stats and dashboards are presented and how it stats be filtered, however in the context of all APIs running in the gateway as opposed to just an individual API. For operators of the platform, this page is especially important to monitor overall performance and health for a logical gateway and all nodes within it. It can also be handy to identify if a specific API is being problematic:
Gateways pageâanalytics section
The gateways page documentation can be accessed from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-gateway-settings.html#GUID-A4FF2A7E-1CEF-4396-BD50-54D506F711E7
A backend service is basically an unmanaged REST endpoint fronted by the API Platform's API Gateway.
A service registered in this page can be referenced from the API implementation page that way preventing a backend endpoint URLs to be manually typed every time an API is created.
Management portalâservices page
Once a service is created, it can be edited just clicking over it. This will take the user to the service settings page described subsequently.
Settings section, it is possible to edit a REST endpoint name and its corresponding URL. Although in version 17.3.x only one endpoint can be entered per service, in future versions it will be possible to assign multiple endpoints, which will be useful as each environment (for example, dev, test) can have its own endpoint.
From this same section it is also possible to assign a
Service Account which is useful if the backend REST endpoint requires some form of authentication.
Refer to next section Service accounts for further information on authentication types supported.
Services pageâsettings section
Service Accountspage is used to effectively store authentication secrets that can be used by service (registered in the services page) when calling backend endpoint URLs that require some form of authentication and authorization. In version 17.3.x, two authentication types are supported, HTTP Basic Authentication and OAuth 2.0.
Management portalâservices accounts page
Once a service account is created, it can be edited just clicking over it. This will take the user to the service accounts settings page described subsequently.
From the settings section it is possible to change the authentication type used in the service accounts, along with its relevant details (for example, username and password in the case of Basic Authentication):
Services pageâsettings section
Management portalâroles page
To better understand users and roles of in Oracle APIP CS, the following diagram illustrates some of the main roles available in the platform (including in Apiary) and how they relate to the different components of the platform:
- API manager: People responsible for managing the API lifecycle, which includes designing, implementing, and versioning APIs. Also responsible for managing grants and applications, providing API documentation, and monitoring API performance.
- Service manager: People responsible for managing resources defining backend services. This includes for example managing service accounts.
- Application developer: API consumers granted self-service access rights to discover and register APIs, view API documentation, and manage applications using the developer portal.
- API Designers: This role does not exist in the API platform, but rather to represent API managers and/or application developers that have access to Apiary and therefore can either produce API designs, participate in the API design process and/or associate Apiary documentation to a specific API in the APIs page.
That as of version 17.3.x of the platform, users are not integrated with Apiary. Therefore, Apiary has its own user store.
- Gateway manager: Operations team members responsible for deploying, registering, and managing gateways. They may also manage API deployments to their gateways when issued the deploy API grant by an API manager.
- Administrator: System administrators responsible for assigning people roles in the system. Administrators possess the rights of all other roles and rights to all objects in the system.
- Gateway runtime: This role indicates a service account used to communicate from the gateway to the portal.
As previously described, grants are available in multiple pages of the portal, like the APIs page, applications page and gateway page. In Oracle APIP CS certain grants are assign by default to the different roles available as it has been illustrated in the following diagram:
Oracle APIP CS-roles to grants mapping
Similarly, the following diagram provides grants centric view, where each grant and the group it belongs to is described and then also mapped to the corresponding user roles for which the grant is available by default:
Oracle APIP CSâgrants to roles mapping
The roles page documentation can be accessed from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-roles.html#GUID-F87B1C66-355F-441C-97B5-34D8C42C96C1
In versions 17.2.x, 17.3.x, and of the API platform, users and roles are still managed via theÂ WebLogic Management ConsoleÂ which is accessible through the same URL as the management console but with the URIÂ
Therefore, when handling users and groups in Oracle APIP CS, it is critical to understand that each role has a corresponding WebLogic user group. And therefore, when creating users in WebLogic console, they should be assigned to the corresponding WebLogic group that matches the Oracle APIP CS role to which the user is to belong to.
Oracle APIP CS Role
Details on managing users and group are available in the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-users-and-groups.html#GUID-055CE442-17FB-4CB7-848D-A762540F6DEE
There are two main sections.
Management portal â platform general settings
As the name suggests, from this section, properties specific to the developer portal can be set. For example, enabling or disabling the portal, defining its base URL, and also enabling or disabling the display of the application keys once in the portal, all can be managed via this section:
Management Portal â Developer Portal Settings
Developer Portal is a web-based application meant to be used by application developers and/or API implementers in general (that is, API managers, designers) to discover and subscribe to available APIs. The developer portal can also be used to manage applications:
Oracle APIP CSâdeveloper portal
The landing page after a developer has signed in into the developer portal is the API catalog. From here, all APIs a developer has been granted access to, are listed and can be searched upon based on different criteria:
Developer Portal â APIs page
From this page, a developer can access an API's documentation by just clicking on any of the listed APIs. This action will take the user to the API page.
The API page is the one-stop-shop for all API related documentation. It consists of two main sections. The landing section displaying the API overview documentation and the API documentation section that displays the API Blueprint or Swagger document created in Apiary for the API.
Creating comprehensive API overview and Apiary documentation (API Blueprint or Swagger) is extremely important as this is what application developers will be looking at when consuming an API. The better the documentation, the more usage the API will receive. If the API is poorly documented, application developers will avoid its use by finding workaround which could even imply creating new APIs.
Developer Portal â API page
From this page, the API documentation can be accessed (icon with shape of a document located on the left-hand side of the section) as well as a subscription for the API can be created.
The API documentation section displays the Apiary document associated with the API:
API page â documentation
When a developer clicks on the
Subscribe button, the subscription page opens. From here a developer can select which client application is to be subscribed to use the API. Note that for this to work, an application has to be created by the developer. If the relevant application hasn't already been created, a new application can be created directly from this page or from the
My Applications page-covered in the next section:
From this page, developers can create and manage applications that consume APIs. Properties such as application keys, API subscriptions and grants can be managed from this page. Also, analytics information related to the application can be visualized.
As briefly described earlier, In Oracle APIP CS an application represents the consumer of one or more APIs. Applications are uniquely identified with application keys which in turn can be used by policies such as key validation and application rate limiting to restrict access to the API.
My Applications page
When a developer clicks in any of the listed applications, the
Overview section opens. From this section metadata details associated with the application can be detailed, but most importantly the application key can be visualized and also re-issued:
My Applications pageâoverview section
My Applications pageâsubscriptions section
My Applications pageâthe Grants section
Oracle APIP CS was created following an API-first approach. What this means in practice is that all of the functionality available via the portals, in fact more, is also available via the management service REST APIs.
The following diagram illustrates the different resources available through the Oracle APIP CS management service APIs:
Oracle APIP CSâmanagement REST APIs
- Administration service: Accessed through the
/apiplatform/administrationendpoint, this resource delivers platform administration capabilities, such as configuration of platform preferences and management of users and roles.
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfrp/index.html
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfrm/index.html
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfrd/index.html
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfrg/index.html
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfra/index.html
Further information available from the following URL:http://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfrl/index.html
Now that the management APIs have been described, it is equally important to understand in what use cases they could be use.
For example, the management APIs
/instancemgmt/ could be used in any of the following use cases:
- Configuration management: Using the
/management/resource to version control APIs (that is, in a GIT) and manage releases (that is, in Nexus).
- Continuous integration/continuous delivery (CICD): Although related to the previous point, this use case is about using
/management/resources along with CI tool (that is, Jenkins, Hudson, Circle CI) to automate the software development lifecycle (that is, promotion of APIs across environments, regression testing, API contract validations with Dredd).
- Infrastructure as code: A relatively new discipline, infrastructure as code is all about taking infrastructure provisioning automation and management by adopting practices originated in software engineering. By using Oracle Public Cloud (OPC) PaaS APIs (
/instancemgmt) it is possible to also automate the actual provisioning of Oracle APIP CS instances. Then combined with the use of other resources in
/apiplatform/robust automation solutions can be achieved.
- Developer portal extensions: In some scenarios, it might be required to either extend the developer portal, embedded some developer portal functionality within other corporate intranet portals or simply create custom portal front-ends (that is, for individual APIs). All of this is available by using the
As illustrated in the following diagram, plans are used to handle entitlements to one or many APIs such as client applications can subscribe to a given plan and through it, gain access to all APIs associated with it:
Oracle APIP CSâAPI plans
In releases prior 18.1.5, API managers have to first publish each API to the developer portal before developers can discover and subscribe them to client applications.
From release 18.1.5 onwards, a plan can be created in the management portal that entitles (grants access) to any given API. Once this is done, an API manager can publish the plan to the developer portal (as opposed to just the individual API) so sub-sequentially, developers can discover and subscribe to the plan via the developer portal.
Because plans effectively act as a unit-of-visibility to all APIs associated with it, they provide a great mechanism to apply common quality-of-service controls, like for example, limit the total number of calls that can, within a given timeframe, be collectively made to APIs within the plan:
Plans also play an important role in enabling the so-called API economy. If properly implemented, a plan can act as act as an accounting log of who/when/which/how many times any given API within the plan was consumed. With such information at hand, monetizing on APIs (term known as API monetization) becomes more a business strategy question as the core technology building blocks would be in placed to enable such business capability.
Apiary is a cloud-based platform specialized in the delivery robust API-design first, API documentation, API mocking and API unit testing capabilities. Apiary is also a great tool for team collaboration as it offers the ability to create feedback loops between API designers and API consumers very early in the development life cycle.
The following diagram illustrates the capabilities available in Apiary:
It is worth noting that although Oracle acquired Apiary in January 2017, the partnership between both companies started way before that. For this reason, the integration of both products was already in place prior acquisition and launch of Oracle APIP CS. This integration is explained in far more detail in Chapter 3,Designing the API as it shows from design to publication how Apiary and the Oracle API Platform are used together seamlessly.
Comparison ofÂ Apiary plans
For teams that are just getting started with API-first design and Apiary, the recommendation is to sign up for a free account to start with. As the skills of the team mature and more product features are needed, at this point upgrading to a paid plan is probably a good idea.
Apiary offers two views:Â personal view andÂ team view. Each view provides a different set of navigation options. Personal view focuses on API projects whereas team view in the management of team assets and people.
When an API designer selects to be in personal view mode, navigation options relevant for creating, editing, and managing API projects become visible. Following a description of the options available in this view.
The landing page after an API designer signs in, from this page an API Blueprint or Swagger file for an API project can be edited. There are a few features available in the editor that are worth highlighting.
As a designer works on the API design, the right-hand side of the screen dynamically renders to show the specification in styled HTML 5. Just as regular API consumers (that is, app developers) would look at it. From this same page, it is possible to test API resources again just like API consumers would-Apiary comes with a mock-up engine that automatically generates API mockups on the fly. Moreover, as the API design takes place, inline conventions and pattern validation also occurs thus ensuring that the design is consistent with the team-specified styles (described later in the chapter). This and more features will be covered inÂ Chapter 3,Â Designing the API in greater detail.
Personal view-create/search API project
When a user clicks on
Create New API Project, then the
New API window appears. From here the user can decide to create an API only accessible by its creator, a
Personal API, or an API that can be viewed and edited by the entire team, a
Personal viewâcreate/search API project
A concept worth understanding up-front when creating a new API project is the notion that an API belongs to either a person or a team. When an API belongs to the person, only the user that created the API can see it and edit it. However, when a project belongs to the team, the entire team can see it and those with designated rights can also edit it.
As the design of the API progresses and developers start trying the API and start to provide feedback, from the Inspector section it is possible to also see what tests are being executed and what resources are being called. This is very useful as if issues occur it is also possible to drill down into each call and check requests and response payloads and HTTP headers:
From this page, a user (designer or developer) can visualize a rendered API design in styled HTML5 and also try the different resources. Pretty much the same is page shown on the right-hand side of the editor.
One of the best and most important features of Apiary is the ability to verify that the implementation of an API is actually consistent with its design, for example, an API blueprint. This is critical because in many occasions developers might deviate from the actual design and without the ability to test this, issues could occur later in the lifecycle whereby API consumers don't get the API they expected.
To prevent this issue from materializing, the Test your API feature of Apiary allows for a utility call Dredd to be download and installed. Dredd can then be used to automatically verify that a service endpoint matches a given API definition:
Note that the use of Dredd for API unit testing is covered extensively in Chapter 3,Designing the API.
API Domainâused to uniquely determine an URL to access the API documentation.
- Enable/disable cross-origin requests headers (
- Enable/disable a
Proxyso instead of using the mock-up engine of Apiary, route the calls to the implemented API endpoints.
- Remove the API project.
- Transfer ownership of the API to the team.
- Make the project private or public.
- Link the project to a GitHub account. If one doesn't exist, it can be configured.
Personal viewâproject settings
As the name suggests, when the team view is selected, navigation options related to the management of the team become available. From here it is possible to manage users, APIs that belong to the team and most importantly theÂ stylesthat apply to all API projects within the team.
From this page, APIs that belong to the team can be searched upon and accessed. This page is very useful as members of the team can discover API designs that already exist, which can help avoid duplication, but also ensures that members of the team can learn from each other:
This page can only be accessed by admin users and is broken down into 3 sections.
Dashboard section provides a summary of the validation outcomes for all APIs within the team. This is extremely useful especially in large teams so admin users can get quick feedback on the status of API designs being created.
Assertions section, assertions can be enabled, disabled, modified or created (for the last two options a user needs to switch to
Advanced Mode). Assertions are the actual rules tested against the API designs in real time from the editor:
Styles â assertions
Playground section, as the name suggests, can be used to test assertions. Either existing ones that are being modified, or new ones:
From the people page of the team view, admin users can manage the team. For example, new users can be invited to join the team and/or existing users can be made admins or regular users.
- Regular: Non-admin users that have access to personal view and limited access to team view pages.
- Admin: Administrative users that have access to all full views. Only admin users have access to the people, style and billing pages of the team view:
Team view - people
From this page, some basic default settings can be specified by admin users. The
Team Project Template property is worth highlighting as it allows to specify an API design to use as a template when creating a new project:
The main purpose of this page is to allow admin users to manage the account billing information and the Apiary plan the team is subscribed to. From here it is possible to cancel the existing plan or upgrade to a new one.
The chapter started by providing a comprehensive walk through of how Oracle's API offering evolved from being a traditional SOA stack, into a 3rd generation API Platform, capable of satisfying numerous use cases and scenarios, both on-premise and cloud.
The chapter continued by providing a detailed overview of the Oracle API Platform Cloud Service (APIP CS) architecture and Apiary. Comprehensive diagrams were introduced to illustrate the different features available in the product, all of which were described throughout the chapter.
The chapter then carried on to describe the API Platform's management portal and developer portals. The different pages and sections within each were described in order to provide a holistic view of the capabilities offered by the product, also including a description of the platform's management REST APIs, its resources and use cases.
The chapter ended by providing an overview of Apiary although not in great detail as more information regarding how to make use of Apiary is available in Chapter 3, Designing the API.
In the next chapter, a real-world inspired case study will be described where it is explained the motivations and business drivers for adopting an API Management platform.