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.
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.
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:
FORMAT: 1A # HumanResourceService Human Resource Service is an API to manage Human Resources. ## Employees Collection [/employees] ### Get all employees [GET /employees] Get all employees. + Response 200 (application/json) { "items": [ { "employee_id": 100, "first_name": "Steven", "last_name": "King", "email": "SKING", "phone_number": "515.123.4567", "hire_date": "1987-06-17T04:00:00Z", "job_id": "AD_PRES", "salary": 24000, "commission_pct": null, "manager_id": null, "department_id": 90, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/100" } ] }, { "employee_id": 101, "first_name": "Neena", "last_name": "Kochhar", "email": "NKOCHHAR", "phone_number": "515.123.4568", "hire_date": "1989-09-21T04:00:00Z", "job_id": "AD_VP", "salary": 17000, "commission_pct": null, "manager_id": 100, "department_id": 90, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/101" } ] }, { "employee_id": 102, "first_name": "Lex", "last_name": "De Haan", "email": "LDEHAAN", "phone_number": "515.123.4569", "hire_date": "1993-01-13T05:00:00Z", "job_id": "AD_VP", "salary": 17000, "commission_pct": null, "manager_id": 100, "department_id": 90, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/102" } ] }, { "employee_id": 103, "first_name": "Alexander", "last_name": "Hunold", "email": "AHUNOLD", "phone_number": "590.423.4567", "hire_date": "1990-01-03T05:00:00Z", "job_id": "IT_PROG", "salary": 9000, "commission_pct": null, "manager_id": 102, "department_id": 60, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/103" } ] }, { "employee_id": 104, "first_name": "Bruce", "last_name": "Ernst", "email": "BERNST", "phone_number": "590.423.4568", "hire_date": "1991-05-21T04:00:00Z", "job_id": "IT_PROG", "salary": 6000, "commission_pct": null, "manager_id": 103, "department_id": 60, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/104" } ] }, { "employee_id": 105, "first_name": "David", "last_name": "Austin", "email": "DAUSTIN", "phone_number": "590.423.4569", "hire_date": "1997-06-25T04:00:00Z", "job_id": "IT_PROG", "salary": 4800, "commission_pct": null, "manager_id": 103, "department_id": 60, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/105" } ] }, { "employee_id": 106, "first_name": "Valli", "last_name": "Pataballa", "email": "VPATABAL", "phone_number": "590.423.4560", "hire_date": "1998-02-05T05:00:00Z", "job_id": "IT_PROG", "salary": 4800, "commission_pct": null, "manager_id": 103, "department_id": 60, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/106" } ] }, { "employee_id": 107, "first_name": "Diana", "last_name": "Lorentz", "email": "DLORENTZ", "phone_number": "590.423.5567", "hire_date": "1999-02-07T05:00:00Z", "job_id": "IT_PROG", "salary": 4200, "commission_pct": null, "manager_id": 103, "department_id": 60, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/107" } ] }, { "employee_id": 108, "first_name": "Nancy", "last_name": "Greenberg", "email": "NGREENBE", "phone_number": "515.124.4569", "hire_date": "1994-08-17T04:00:00Z", "job_id": "FI_MGR", "salary": 12000, "commission_pct": null, "manager_id": 101, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/108" } ] }, { "employee_id": 109, "first_name": "Daniel", "last_name": "Faviet", "email": "DFAVIET", "phone_number": "515.124.4169", "hire_date": "1994-08-16T04:00:00Z", "job_id": "FI_ACCOUNT", "salary": 9000, "commission_pct": null, "manager_id": 108, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/109" } ] }, { "employee_id": 110, "first_name": "John", "last_name": "Chen", "email": "JCHEN", "phone_number": "515.124.4269", "hire_date": "1997-09-28T04:00:00Z", "job_id": "FI_ACCOUNT", "salary": 8200, "commission_pct": null, "manager_id": 108, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/110" } ] }, { "employee_id": 111, "first_name": "Ismael", "last_name": "Sciarra", "email": "ISCIARRA", "phone_number": "515.124.4369", "hire_date": "1997-09-30T04:00:00Z", "job_id": "FI_ACCOUNT", "salary": 7700, "commission_pct": null, "manager_id": 108, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/111" } ] }, { "employee_id": 112, "first_name": "Jose Manuel", "last_name": "Urman", "email": "JMURMAN", "phone_number": "515.124.4469", "hire_date": "1998-03-07T05:00:00Z", "job_id": "FI_ACCOUNT", "salary": 7800, "commission_pct": null, "manager_id": 108, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/112" } ] }, { "employee_id": 113, "first_name": "Luis", "last_name": "Popp", "email": "LPOPP", "phone_number": "515.124.4567", "hire_date": "1999-12-07T05:00:00Z", "job_id": "FI_ACCOUNT", "salary": 6900, "commission_pct": null, "manager_id": 108, "department_id": 100, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/113" } ] }, { "employee_id": 114, "first_name": "Den", "last_name": "Raphaely", "email": "DRAPHEAL", "phone_number": "515.127.4561", "hire_date": "1994-12-07T05:00:00Z", "job_id": "PU_MAN", "salary": 11000, "commission_pct": null, "manager_id": 100, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/114" } ] }, { "employee_id": 115, "first_name": "Alexander", "last_name": "Khoo", "email": "AKHOO", "phone_number": "515.127.4562", "hire_date": "1995-05-18T04:00:00Z", "job_id": "PU_CLERK", "salary": 3100, "commission_pct": null, "manager_id": 114, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/115" } ] }, { "employee_id": 116, "first_name": "Shelli", "last_name": "Baida", "email": "SBAIDA", "phone_number": "515.127.4563", "hire_date": "1997-12-24T05:00:00Z", "job_id": "PU_CLERK", "salary": 2900, "commission_pct": null, "manager_id": 114, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/116" } ] }, { "employee_id": 117, "first_name": "Sigal", "last_name": "Tobias", "email": "STOBIAS", "phone_number": "515.127.4564", "hire_date": "1997-07-24T04:00:00Z", "job_id": "PU_CLERK", "salary": 2800, "commission_pct": null, "manager_id": 114, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/117" } ] }, { "employee_id": 118, "first_name": "Guy", "last_name": "Himuro", "email": "GHIMURO", "phone_number": "515.127.4565", "hire_date": "1998-11-15T05:00:00Z", "job_id": "PU_CLERK", "salary": 2600, "commission_pct": null, "manager_id": 114, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/118" } ] }, { "employee_id": 119, "first_name": "Karen", "last_name": "Colmenares", "email": "KCOLMENA", "phone_number": "515.127.4566", "hire_date": "1999-08-10T04:00:00Z", "job_id": "PU_CLERK", "salary": 2500, "commission_pct": null, "manager_id": 114, "department_id": 30, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/119" } ] }, { "employee_id": 120, "first_name": "Matthew", "last_name": "Weiss", "email": "MWEISS", "phone_number": "650.123.1234", "hire_date": "1996-07-18T04:00:00Z", "job_id": "ST_MAN", "salary": 8000, "commission_pct": null, "manager_id": 100, "department_id": 50, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/120" } ] }, { "employee_id": 121, "first_name": "Adam", "last_name": "Fripp", "email": "AFRIPP", "phone_number": "650.123.2234", "hire_date": "1997-04-10T04:00:00Z", "job_id": "ST_MAN", "salary": 8200, "commission_pct": null, "manager_id": 100, "department_id": 50, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/121" } ] }, { "employee_id": 122, "first_name": "Payam", "last_name": "Kaufling", "email": "PKAUFLIN", "phone_number": "650.123.3234", "hire_date": "1995-05-01T04:00:00Z", "job_id": "ST_MAN", "salary": 7900, "commission_pct": null, "manager_id": 100, "department_id": 50, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/122" } ] }, { "employee_id": 123, "first_name": "Shanta", "last_name": "Vollman", "email": "SVOLLMAN", "phone_number": "650.123.4234", "hire_date": "1997-10-10T04:00:00Z", "job_id": "ST_MAN", "salary": 6500, "commission_pct": null, "manager_id": 100, "department_id": 50, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/123" } ] }, { "employee_id": 124, "first_name": "Kevin", "last_name": "Mourgos", "email": "KMOURGOS", "phone_number": "650.123.5234", "hire_date": "1999-11-16T05:00:00Z", "job_id": "ST_MAN", "salary": 5800, "commission_pct": null, "manager_id": 100, "department_id": 50, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/124" } ] } ], "hasMore": true, "limit": 25, "offset": 0, "count": 25, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/" }, { "rel": "edit", "href": "http://localhost:9090/ords/hr/employees/" }, { "rel": "describedby", "href": "http://localhost:9090/ords/hr/metadata-catalog/employees/" }, { "rel": "first", "href": "http://localhost:9090/ords/hr/employees/" }, { "rel": "next", "href": "http://localhost:9090/ords/hr/employees/?offset=25" } ] } ### Get an employee [GET /employees/{id}] Get a particular employee by providing an identifier. + Response 200 (application/json) { "employee_id": 100, "first_name": "Steven", "last_name": "King", "email": "SKING", "phone_number": "515.123.4567", "hire_date": "1987-06-17T04:00:00Z", "job_id": "AD_PRES", "salary": 24000, "commission_pct": null, "manager_id": null, "department_id": 90, "links": [ { "rel": "self", "href": "http://localhost:9090/ords/hr/employees/100" }, { "rel": "edit", "href": "http://localhost:9090/ords/hr/employees/100" }, { "rel": "describedby", "href": "http://localhost:9090/ords/hr/metadata-catalog/employees/item" }, { "rel": "collection", "href": "http://localhost:9090/ords/hr/employees/" } ] } ### Create an employee [POST /employees] Create an employee, by using post with the complete payload + Request (application/json) {"LAST_NAME":"TESTINSERT", "FIRST_NAME":"TESTFIRST", "EMAIL":"TESTMAIL", "HIRE_DATE":"25-JUN-15", "JOB_ID":"IT_PROG", "SALARY":6000, "MANAGER_ID":103, "DEPARTMENT_ID":60} + Response 201 (application/json) { "employee_id": 220, "first_name": "TESTFIRST", "last_name": "TESTINSERT", "email": "TESTMAIL", "phone_number": null, "hire_date": "2015-06-25T04:00:00Z", "job_id": "IT_PROG", "salary": 6000, "commission_pct": null, "manager_id": 103, "department_id": 60 } ### Update an employee [PUT /employees/{id}] Update an employee, by using put with the a payload containing: last_name, job_id, salary and department_id. + Parameters + id: `220` (number, required) - Id of an employee. + Request (application/json) {"LAST_NAME":"TESTUPDATE", "JOB_ID":"SA_REP", "SALARY":8000, "DEPARTMENT_ID":80} + 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 } ## Departments Collection [/departments] ### Get a department [GET /department/{id}] Get a particular department by providing an identifier. + Parameters + id: `30` (number, required) - Id of a department. + Response 200 (application/json) { "department_id": 30, "department_name": "Purchasing", "manager_id": 114, "location_id": 1700 } ### Get a department and employee [GET /departments/{department_id}/employees/{employee_id}] Get a particular department by providing a department identifier and a particular employee within that department by providing an employee identifier. + Parameters + department_id: `30` (number, required) - Id of a department. + employee_id: `119` (number, required) - Id of an employee. + Response 200 (application/json) { "department_id": 30, "department_name": "Purchasing", "employee_id": 119, "first_name": "Karen", "last_name": "Colmenares" } 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:
// Maven : Add these dependecies to your pom.xml (java6+) // <dependency> // <groupId>org.glassfish.jersey.core</groupId> // <artifactId>jersey-client</artifactId> // <version>2.8</version> // </dependency> // <dependency> // <groupId>org.glassfish.jersey.media</groupId> // <artifactId>jersey-media-json-jackson</artifactId> // <version>2.8</version> // </dependency> import javax.ws.rs.client.Client; import javax.ws.rs.client.ClientBuilder; import javax.ws.rs.client.Entity; import javax.ws.rs.core.Response; import javax.ws.rs.core.MediaType; Client client = ClientBuilder.newClient(); Response response = client.target("https://private-b4874b1-humanresourceservice.apiary-mock.com/employees") .request(MediaType.TEXT_PLAIN_TYPE) .get(); System.out.println("status: " + response.getStatus()); System.out.println("headers: " + response.getHeaders()); System.out.println("body:" + response.readEntity(String.class)); 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:
from urllib2 import Request, urlopen request = Request('https://private-b4874b1-humanresourceservice.apiary-mock.com/employees') response_body = urlopen(request).read() print response_body 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).
