Oracle API Platform Cloud Service: Design-First approach and using Oracle Apiary

At the Oracle Partner PaaS Summer Camps VII 2017 in Lisbon last year, at the end of august, I attended the API Platform Cloud Service & Integration Cloud Service bootcamp.

In a series of article’s I will give a high level overview of what you can do with Oracle API Platform Cloud Service. The version used of Oracle API Platform CS was Release 17.3.3 — August 2017.

See https://docs.oracle.com/en/cloud/paas/api-platform-cloud/whats-new/index.html to learn about the new and changed features of Oracle API Platform CS in the latest release.

In preparation of creating an API Blueprint document, I took a closer look at Oracle REST Data Services and used the RESTful Services feature in Oracle SQL Developer, to generate example JSON payload’s based on some tables in the “HR’ schema. For more information about this, see my article “Oracle REST Data Services (ORDS)”.
_{[https://technology.amis.nl/2018/01/22/oracle-rest-data-services-ords/]}

In this first article in the series about Oracle API Platform CS, the focus will be on the Design-First approach and using Oracle Apiary.

Short overview of Oracle API Platform Cloud Service

Oracle API Platform Cloud Service enables companies to thrive in the digital economy by comprehensively managing the full API lifecycle from design and standardization to documenting, publishing, testing and managing APIs. These tools provide API developers, managers, and users an end-to-end platform for designing, prototyping. Through the platform, users gain the agility needed to support changing business demands and opportunities, while having clear visibility into who is using APIs for better control, security and monetization of digital assets.
_{[https://cloud.oracle.com/en_US/api-platform/datasheets]}

Architecture

Management Portal:
APIs are managed, secured, and published using the Management Portal. The Management Portal is hosted on the Oracle Cloud, managed by Oracle, and users granted API Manager privileges have access.

Gateways:
API Gateways are the runtime components that enforce all policies, but also help in collecting data for analytics. The gateways can be deployed anywhere – on premise, on Oracle Cloud or to any third party cloud providers.

Developer Portal:
After an API is published, Application Developers use the Developer Portal to discover, register, and consume APIs. The Developer Portal can be customized to run either on the Oracle Cloud or directly in the customer environment on premises.
_{[https://cloud.oracle.com/opc/paas/datasheets/APIPCSDataSheet_Oct2017.pdf]}

More about this follows in another article in the series.

Design-First approach

API-First Development is a fundamental paradigm shift in the process of API design where APIs are built before applications and mirror the goals and objectives of the company. API-First Development is also commonly referred to as Design-First Development.

Before a developer builds a web, mobile, or other application, they develop the API first, then start defining the channels that the API will be available on. Developers kick off the development process discussing the API with their potential customers, generate use cases, and mock up the API before even developing the application.
_{[https://cloud.oracle.com/opc/paas/datasheets/Apiary-Datasheet-Oracle.pdf]}

“API-First Development” experience is one of the Key Design Principles of Oracle API Platform Cloud Service. The Developer Portal, tightly linked with Apiary, allows application developers to search for, learn about, test and register to use APIs, and then track their own usage.
_{[https://cloud.oracle.com/opc/paas/datasheets/APIPCSDataSheet_Oct2017.pdf]}

Oracle Apiary provides you with the ability to design APIs using either API Blueprint or Swagger 2.0. From these description files, Oracle Apiary generates interactive documentation and a console for making calls to the APIs from the UI.
_{[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/oracle-apiary-integration.html]}

API Blueprint

API Blueprint is a documentation-oriented web API description language. The API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax used to describe a web API.

An API Blueprint document – a blueprint – is a plain text Markdown document describing a Web API in whole or in part. The document is structured into logical sections. Each section has its distinctive meaning, content and position in the document.
_{[https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md]}

For the Full Language Specification of API Blueprint see for example:
https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md

For an API Blueprint tutorial see for example:
https://docs.oracle.com/cloud/apiary/api_101/api_blueprint_tutorial/index.html

The recommended file extension for API Blueprint is .apib

Oracle Apiary

Apiary provides the world’s first platform, API Flow, specifically designed to help companies accelerate and control the design, development, and documentation of their APIs and microservices. This allows its users to create products and services that customers, business partners, and even machines love to use.

Apiary API Flow is an open platform supporting both API Blueprint and OpenAPI (Swagger). The platform provides tools to developers for every step of an API-First Development Lifecycle and delivers several significant benefits to a team of developers.
_{[https://cloud.oracle.com/opc/paas/datasheets/Apiary-Datasheet-Oracle.pdf]}

In this article I will discuss some of the functionality of Oracle Apiary, but not all. Please see the available documentation for more details.

Go to https://apiary.io/ to start Oracle Apiary.

You can Sign Up for free with a GitHub, Twitter or email account. Once you have done that, you can Sign In to start working with Oracle Apiary.

Via menu | Create New API Project, the New API wizard is started, where you can choose between creating a Personal API or Team API and in the field “New API name” you can fill in your API name, for example: HumanResourceService.

Then click on button “Create API”.

Apiary Editor

The “HumanResourceService” API automatically shows up in the Apiary Editor. The header item “Editor” is high-lighted.

The Apiary Editor, contains 3 panes, with an API Blueprint tutorial (a polls service, which allows consumers to view polls and vote in them) already in place. For more information about that tutorial, see: https://help.apiary.io/api_101/api_blueprint_tutorial/

The Apiary Editor is the foundation of your API design. Apiary Editor supports API Blueprint and Swagger API Description languages.
_{[https://help.apiary.io/tools/apiary-editor/]}

In the left pane (Editor), an API Blueprint document, structured into logical sections, is shown.
The center pane (Documentation preview) shows what your API document will look like when rendered as documentation. It also lets you to try out your API as you build. The documentation preview is dynamically updated as you type in the Editor.
In the right pane the code examples/console is shown.

You can modify the API Blueprint tutorial document to fulfill your needs, or use some other text editor and copy and paste it into the Editor.

As described in my previous article, mentioned above, in the table below I summarized the requests that I created:

Request name	Method	Request URL
GetAllEmployeesRequest	GET	http://localhost:9090/ords/hr/demo1/employees/
CreateEmployeeRequest	POST	http://localhost:9090/ords/hr/demo1/employees/
GetEmployeeRequest	GET	http://localhost:9090/ords/hr/demo1/employees/100
UpdateEmployeeRequest	PUT	http://localhost:9090/ords/hr/demo1/employees/219
GetDepartmentRequest	GET	http://localhost:9090/ords/hr/demo1/departments/30
GetDepartmentEmployeeRequest	GET	http://localhost:9090/ords/hr/demo1/departments/30/employees/119

The first step for creating an API Blueprint document is to specify the Metadata, API name and description.

Metadata section:
The API Blueprint document starts with a Metadata section, which consists of Key-Value pairs. Each Key is separated from its Value by a colon (:). One pair per line. The FORMAT keyword is required and denotes that document is API Blueprint.

FORMAT: 1A

API name & overview section:
In the API name & overview section, the API name is defined by the first Markdown header in the API Blueprint document.

# HumanResourceService

Human Resource Service is an API to manage Human Resources.

Resource section:
An API consists of resources specified by their URIs.

In line with the API Blueprint tutorial (a polls service, which allows consumers to view polls and vote in them), I used a Resource section with as format:
## <identifier> [<URI template>]

For example:
## Employees Collection [/employees]

Action section:
You should specify each action you may make on a resource. An action is specified with a sub-heading with the name of the action followed by the HTTP method.

Within the Resource section I created multiple Action sections, with as format:
### <identifier> [<HTTP request method> <URI template>]

For example:
### Get all employees [GET /employees]

As you can see, in my API, some Action sections contain an URI parameters section and/or a Request section and a Response section.

URI parameters section:
The URI parameters section describes any URI parameters specific to the action, with as format:
+ <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) – <description>

For example:
+ id: `220` (number, required) – Id of an employee.

Request section:
For the Request sections the following format was used:
+ Request <identifier> (<Media Type>)

For example:
+ Request (application/json)

{“LAST_NAME”:”TESTUPDATE”, “JOB_ID”:”SA_REP”, “SALARY”:8000, “DEPARTMENT_ID”:80}

Remark:
Specifying the media type generates a HTTP Content-Type header.

Response section:
For the Response sections the following format was used:
+ Response <HTTP status code> (<Media Type>)

For example:
+ Response 200 (application/json)

{
“employee_id”: 220,
“first_name”: “TESTFIRST”,
“last_name”: “TESTUPDATE”,
“email”: “TESTMAIL”,
“phone_number”: null,
“hire_date”: “2015-06-25T04:00:00Z”,
“job_id”: “SA_REP”,
“salary”: 8000,
“commission_pct”: null,
“manager_id”: 103,
“department_id”: 80
}

Remark:
Specifying the media type generates a HTTP Content-Type header.

My HumanResourceService.apib therefor looks like:

Apiary Editor, instant feedback

The Apiary Editor gives you instant feedback on any warnings or errors in your document as you type. The feedback will include line numbers and explanations for the warnings and errors, which will take you to the corresponding line in the editor when clicked.
_{[https://help.apiary.io/tools/apiary-editor/]}

For example:

The semantic issues shown above where solved by, changing the URI template to:

### Get a department and employee [GET /departments/{department_id}/employees/{employee_id}]

After changing the content of the API Blueprint tutorial (a polls service, which allows consumers to view polls and vote in them) in order to describe the functionality of the HumanResourceService, the Apiary Editor looks like:

Mock Server

The Mock Server allows you to try out your API as you design it, giving immediate feedback along the way in how it may be used.

The Mock Server accomplishes this by listening for requests as you’ve defined them in your blueprint. When a request is received to your Mock Server for a URL you’ve defined, the corresponding response for that request will be returned.
_{[https://help.apiary.io/tools/mock-server/]}

The Mock Server for the “HumanResourceService” API is listening at:
http://private-b4874b1-humanresourceservice.apiary-mock.com

You will have your own private URL for the Mock Server. This is to ensure that other users do not see the traffic you’re sending to the server.
_{[https://help.apiary.io/tools/mock-server/]}

Interacting with the Mock Server can be done:

• Directly
• By using code examples
• By using the console

Interacting with the Mock Server directly
This URL may be used to interact directly with the server. You can make requests with applications like curl or Paw to that URL and will get responses defined in the API Description.
_{[https://help.apiary.io/tools/mock-server/]}

Interacting with the Mock Server by using code examples
Apiary provides code examples that you may use to interact with the Mock Server. You can get to these examples by clicking on any action in the documentation.
_{[https://help.apiary.io/tools/mock-server/]}

Interacting with the Mock Server by using the console
The console in the documentation is where you can send requests to the Mock Server directly from the documentation (along with the Debugging Proxy and your production server). You can get to this by clicking on an action in the documentation, then clicking “Switch to Console” in the machine column.
_{[https://help.apiary.io/tools/mock-server/]}

Interactive Documentation

When you don’t need to see the left pane (Editor) anymore, you can switch in the header to “Documentation”.

The interactive documentation contains two main columns: the human and machine columns. These two columns provide the separation that is important for reading the documentation and actually using tooling to interact with it.
_{[https://help.apiary.io/tools/interactive-documentation/]}

After clicking on an action (for example: “Get all employees”) in the documentation (human column) the right pane (machine column) shows code examples.

Default the “Raw” type is selected, but there is a drop down that has a list of the available languages for the code examples.

When choosing for example “Java” as language for the code example, the following is shown:

This “Java” code example can be used to interact with the Mock Server.

When choosing for example “Python” as language for the code example, the following is shown:

This “Python” code example can be used to interact with the Mock Server.

After clicking on an action (for example: “Get all employees”) in the documentation (human column) and then in the right pane (machine column) clicking on button “Switch to Console” (or on the button “Try” in the code example), the Console is shown.

For the action “Get all employees”, in line with the specifications, the URI Parameters, Headers and Body parts are empty.

When you click on the button “Call Resource”, the response is shown:

After clicking on the action “Create an employee” in the documentation (human column) and then in the right pane (machine column) clicking on button “Switch to Console”, the following is shown.

For the action “Create an employee”, in line with the specifications, the Headers part is filled.

For the action “Create an employee”, in line with the specifications, the Body part is filled.

After clicking on the action “Get a department and employee” in the documentation (human column) and then in the right pane (machine column) clicking on button “Switch to Console”, the following is shown.

For the action “Get a department and employee”, in line with the specifications, the URI Parameters part is filled.

API Inspector

Each request and response from the Mock Server is logged in the API Inspector, which can be found by clicking “Inspector” in the Apiary header. There you will see each request received, each response given, and any validation errors that were found.
_{[https://help.apiary.io/tools/api-inspector/]}

For example:

For each request (by clicking on it) more details are available:

API Test

When you click on the header item “Test”, the following is shown.

For more information about testing your API , please see the available documentation.

Summary

In this first article in the series about Oracle API Platform Cloud Service, the focus is on the Design-First approach and using Oracle Apiary.

“API-First Development” experience (commonly referred to as Design-First Development) is one of the Key Design Principles of Oracle API Platform Cloud Service. Developers kick off the development process discussing the API with their potential customers, generate use cases, and mock up the API before even developing the application.

The Developer Portal of API Platform CS is tightly linked with Oracle Apiary.

Oracle Apiary provides you with the ability to design APIs using either API Blueprint or Swagger 2.0. From these description files, Oracle Apiary generates interactive documentation and a console for making calls to the APIs from the UI.

This article shows you how, with the help of Oracle Apiary, a “HumanResourceService” API is created, based on API Blueprint and example JSON payload’s (based on some tables in the “HR’ schema).