The Oracle API Platform Cloud Service is a 3^rd 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.

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, 3^rd generation.

But what exactly is a 3^rd 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.

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:

As SOA continued to gain popularity, Oracle's offer also evolved to offer richer capabilities in support of Service Oriented Architectures (SOA).

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:

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.

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.

At this point a new architectural component was introduced in the majority of solutions: the API Gateway. The purpose of the API Gateway was (and still is to an extend) to not only provide the security capabilities offered previously by XML Gateways, but also the message routing capabilities offered by ESBs, however in the context of REST APIs, and thus supporting different message notations (like for example the JavaScript Object Notation (JSON) as alternative to XML).

Perhaps because of the obvious similarities of API Gateways to ESBs and also XML Gateways, majority vendors opted to adjust their existing (1^st generation) offerings.

2^nd generation API platforms are therefore nothing but (1^st 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.

For example, Oracle's 2^nd generation API Management Suite (launched between 2013 and 2015), consisted of the following components:

• 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

Although 2^nd 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 2^nd 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.

3^rd 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:

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 3^rd 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 (2^nd generation) API offering as it is much simpler, lighter weight, and scalable. The following chapter describes this in more detail.

As briefly described earlier, the platform is modular, hybrid, and highly customizable. The following figure shows the core components that build up the platform:

As the diagram suggests, the platform consists the following components:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

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

8. 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:

The following section describes each of the pages illustrated in the diagram.

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:

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:

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.

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.

The landing section allows for API policies to be implemented on an API.

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.

The policies that can be applied to request payloads are as following:

1. 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):

2. 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 Management policies as shown in the management portal:

3. Interface management: Policies that deliver capabilities to manage what and how HTTP resources (that is, /<resource>), methods (GET, POST, DELETE, UPDATE) and payloads can be accessed. The following screenshot shows the Interface Management policies as shown in the management portal:

4. 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 Routing policies as shown in the management portal:

5. Other: Complementary policies that deliver additional capabilities that don't fall in any of the above categories like for example service callouts, logging, and custom policies based on groovy scripting. The following image shows the Other policies as shown in the management portal:

The 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:

The publication section allows for API documentation to be created and then published in the developer portal. The documentation consists of two main parts:

1. API overview documentation: Simply put, free text to help describe the functionality and usage of the API. It can be HTML or Markdown text.
2. API specification documentation: The API Blueprint or Swagger specification document for the API created in Apiary:

The 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

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:

The Analytics section 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.

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:

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 grants can also be accessed from this page by clicking on the grants icon (icon with shape of a key located on the left-hand side of the screen).

From the Gateways page, all registered logical gateways and gateways nodes can be visualized and managed. Details such as gateway names and description, load balancer URLs 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):

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:

The 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:

1. 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.
2. Maximum Number of Unbounded Items: Specifies the maximum number of unbounded items that a message can contain. The default value is set to 1024.
3. 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.
4. Maximum Nested Elements in a Message: Specifies the maximum number of nested elements allowed in a message. The default value is 1024 nested elements.

From the 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.

The 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):

The 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:

The 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:

From the Services page backend services can be registered and managed.

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.

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.

From the 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.

Services grants can also be accessed from this page by clicking on the grants icon (icon with shape of a key located on the left-hand side of the screen).

The Service Accounts page 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.

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):

Service accounts grants can also be accessed from this page by clicking on the grants icon (icon with shape of a key located on the left-hand side of the screen).

The roles page lists all the available user roles to which different users and grants can be assigned to.

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:

1. 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.
2. Service manager: People responsible for managing resources defining backend services. This includes for example managing service accounts.
3. Application developer: API consumers granted self-service access rights to discover and register APIs, view API documentation, and manage applications using the developer portal.
4. 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.

5. 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.
6. 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.
7. 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:

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:

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 /console instead.

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.

From the Platform Settings page, general management, and developer portals properties can be set, such as, time zone settings, contact information, base URLs and others.

There are two main sections.

In this section, the Time Zone Settings for the platform can be set:

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:

The API 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:

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:

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.

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:

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.

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:

The subscription section lists all of the APIs that the application is subscribed to. From here it is also possible to unsubscribe any of the APIs:

The Grants section allows for the creator of the application to also share management rights to other users and roles:

Lastly, the Analytics section provides an application-centric view of the usage of those APIs the application is subscribed to. This view can be very useful for developers looking to analyze API usage by any given application:

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 classifies the following management REST APIs:

• Administration service: Accessed through the /apiplatform/administration endpoint, this resource delivers platform administration capabilities, such as configuration of platform preferences and management of users and roles.

• Management service: Accessed through the /apiplatform/management endpoint, this resource delivers equivalent and additional capabilities to those available via the management portal.

• Developer portal: Accessed through the /apiplatform/developers endpoint, this resource delivers equivalent and additional capabilities to those available via the developer portal.

• Gateway controller: Accessed through the /apiplatform/gatewaynode endpoint, this resource delivers gateway administration and monitoring capabilities. This resource is used by the gateway nodes during the registration and join process when installing a gateway.

• Analytics: Accessed through the /apiplatform/analytics endpoint, this resource can be used to retrieve analytics metrics for APIs, applications and gateways.

• Life cycle management: accessed through the /instancemgmt/ endpoint, delivers Oracle APIP CS instance provisioning and management capabilities.

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 /apiplatform/ and /instancemgmt/ could be used in any of the following use cases:

1. Configuration management: Using the /management/ resource to version control APIs (that is, in a GIT) and manage releases (that is, in Nexus).
2. 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).
3. 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.
4. 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 /developers/ resources.

Starting from the release 18.1.5 a new feature is introduced to the API Platform called Plans.

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:

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:

The first step to access Apiary is by opening an account. There are 3 different options to select from. Free, Standard, or Pro:

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.

From this same page, on the top-right hand side, it is possible to search existing API projects, open a project, or create a new one either in API Blueprint or Swagger:

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 Team API:

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:

The project settings page is where properties specific to the API project are defined. There are different options available from this page, worth highlighting:

1. Define API Domain–used to uniquely determine an URL to access the API documentation.
2. Enable/disable cross-origin requests headers (CORS).
3. Enable/disable a Proxy so instead of using the mock-up engine of Apiary, route the calls to the implemented API endpoints.
4. Remove the API project.

5. Transfer ownership of the API to the team.
6. Make the project private or public.
7. Link the project to a GitHub account. If one doesn't exist, it can be configured.

The main purpose of this page is to enable API designers to define who can edit and view the API:

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 styles that 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:

Styles in Apiary are a set of pre-defined modeling patterns and conventions that are used to validate that API designs within the entire team are consistent.

This page can only be accessed by admin users and is broken down into 3 sections.

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

From the 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:

And the 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.

Note that in terms of user roles, Apiary is quite straightforward. There are only two types of users:

1. Regular: Non-admin users that have access to personal view and limited access to team view pages.

2. 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:

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 account settings page can be accessed from any of the views and allows for personal account settings to be managed as well as linking the user account to a GitHub account. From here the user can also choose to leave a team:

The chapter started by providing a comprehensive walk through of how Oracle's API offering evolved from being a traditional SOA stack, into a 3^rd 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.