Post on 22-May-2020
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
API First StrategyDesign, Develop, and Manage APIs on the Cloud
Young Gyu Kim Principal Sales Consultant Oracle Korea, Cloud Platform August 30, 2017
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. |
Safe Harbor Statement
The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.
Confidential – Oracle Internal/Restricted/Highly Restricted 2
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 3
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
Program Agenda
Open API Initiative & Open API Specification
How to Design an API
How to Develop an API
How to Test an API
How to Deploy an API
How to Manage an API
1
2
3
4
5
4
6
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
Open API Initiative & SpecificationOAI OAS
5
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
6
2011.07
2013.04
2013.09
2014.05
2015.11
2016.01
2017.04
SwaggerInitial
Commit
OPEN API InitiativeOpenAPI Spec 2.0
(Swagger Spec 2.0)
API BlueprintInitial
Commit
Swagger Spec 2.0GlueCon 2014
in Colorado
API Blueprint Joined OAI
RAMLInitial
Commit
RAML
Joined OAI
2017.07
Swagger Spec 3.0
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 7
MuleSoft Joins the OpenAPI Initiative: The End of the API Spec Wars
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 8
Open API and RAML: Better Together
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 9
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 10
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 11
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 12
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
How to Design an APISwagger, API Blueprint, RAML
13
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 14
Transform API Descriptions https://apimatic.io/transformer
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 15
Apiary supports Swagger
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 16
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 17
API Blueprint Editor
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 18
Swagger Editor
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 19
Validate API Spec
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 20
Preview
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 21
Github Integration
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 22
API Documentation
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 23
TEST through Mock Server
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 24
TEST through production Server
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 25
Request / Response Header
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 26
Response Data
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Generate Client Source (Code Snippet)cURL, Java, Javascript, Node.JS, Perl, Python, PHP, Ruby, Go, C#, Visual Basic, Groovy, Object-C, Swift
27
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 28
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 29
Java Source Code (maven)
<dependencies><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></dependencies>
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 30
package com.apiarytest.msr.msrclient;
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;
public class ApiCustomer {public static void main(String[] args) {
Client client = ClientBuilder.newClient();Response response = client.target("https://private-15a7b-credemol.apiary-mock.com/search")
.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));
}}
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 31
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 32
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 33
Generate Server (eg, spring boot)
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 34
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 35
Generate Client (eg, java client)
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 36
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 37
Design YAML editor with basic style validationCloud-based YAML editor with predesigned templates, simultaneous style feedback, mocking, and
hosting for API definitions
Develop Code generation with Swagger CodeGenCode generation in 20+ server languages, which can automatically sync with source control hosts like
GitHub, Bitbucket, and GitLab
DocumentInteractive API documentation and
sandbox with SwaggerUI
Interactive API documentation and sandbox, and auto-generation for client SDKs, all hosted in the
cloud with privacy controls
Mock NO Generate a mock of your API to virtualize operations without writing any code
Host NOSecure cloud-based hosting for Swagger definitions and API documentation, with built-in access
controls
Collaborate NOReal-time issue tracking and conversations, team management, role assignment, and permission/
access controls
Deploy NOQuickly deploy your API definitions to API Gateways such as AWS , Microsoft Azure and IBM API
Connect. Automatically generate AWS Lambda functions for serverless deployments.
Version NO Manage multiple versions of API definitions, and retire outdated APIs
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 38
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 39
Transform API Descriptions to formats of your choice
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 40
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 41
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 42
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 43
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
How to Develop an APISwagger Codegen
44
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 45
https://github.com/swagger-api/swagger-codegenInstall Swagger Codegen
$ wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.3/swagger-codegen-cli-2.2.3.jar -O swagger-codegen-cli.jar
$ java -jar swagger-codegen-cli.jar
$ brew install swagger-codegen
Java Version
Homebrew (OS X)
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
• Erlang• Node.js• PHP Lumen• PHP Slim• PHP Silex• Python Flask (Connexion)• Python2 Flask (Connexion)• Ruby on Rails5• Ruby Sinatra• Scala Scalatra• Haskell Servant• ASP.NET Core 1.0• Go Server• NancyFX
46
Swagger Codegen (Server Stub): 23• Java JAX-RS 2.0 spec• Java JAX-RS (Java JAX-RS (Jersey)• Java JAX-RS (Apache CXF 2 / 3)• Java JAX-RS (Resteasy)• Java JAX-RS (Apache CXF
framework on Java EE server supporting CDI)
• Java Spring MVC• Java SpringBoot• Java Undertow• Java MSF4J
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
• async-scala
• csharp
• cpprest (C++, https://github.com/Microsoft/cpprestsdk)
• dart
• flash
• go
• groovy
• java
• jaxrs-cxf-client
• javascript
• javascript-closure-angular
47
Swagger Codegen (API Client): 32• jmeter
• nancyfx
• nodejs-server
• objc
• perl
• php
• python
• qt5cpp (C++, https://www.qt.io/)
• ruby
• scala
• swift
• swift3
• tizen
• typescript-angular2
• typescript-angular
• typescript-node
• typescript-fetch
• akka-scala
• CsharpDotNet2
• clojure
• haskell
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 48
swagger-codegen-cli generate [(-a <authorization> | --auth <authorization>)] [--additional-properties <additional properties>...] [--api-package <api package>] [--artifact-id <artifact id>] [--artifact-version <artifact version>] [(-c <configuration file> | --config <configuration file>)] [-D <system properties>...] [--git-repo-id <git repo id>] [--git-user-id <git user id>] [--group-id <group id>] [--http-user-agent <http user agent>] (-i <spec file> | --input-spec <spec file>) [--ignore-file-override <ignore file override location>] [--import-mappings <import mappings>...] [--instantiation-types <instantiation types>...] [--invoker-package <invoker package>] (-l <language> | --lang <language>) [--language-specific-primitives <language specific primitives>...] [--library <library>] [--model-name-prefix <model name prefix>] [--model-name-suffix <model name suffix>] [--model-package <model package>] [(-o <output directory> | --output <output directory>)] [--release-note <release note>] [--remove-operation-id-prefix] [--reserved-words-mappings <reserved word mappings>...] [(-s | --skip-overwrite)] [(-t <template directory> | --template-dir <template directory>)] [--type-mappings <type mappings>...] [(-v | --verbose)]
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 49
Generate SpringBoot application
$ swagger-codegen generate -v -i "swagger-msr.yaml" \ -l "spring" -o "acme-msr-api" \ --api-package "com.acme.msr.api" \ --model-package "com.acme.msr.model" \ --model-name-suffix "VO" \ --artifact-id "acme-msr-api" \ --group-id "com.acme.msa"
$ cd acme-msr-api
$ mvn clean package
$ mvn spring-boot:run
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 50
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 51
http://localhost:8080/api/swagger-ui.html
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 52
http://localhost:8080/api/api-docs (api-docs.json)
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 53
Swagger2StringBoot.java@SpringBootApplication @EnableSwagger2 @EnableJpaRepositories("com.acme.msr.repository") @ComponentScan(basePackages = { "io.swagger","com.acme.msr.service","com.acme.msr.api" }) @EntityScan("com.acme.msr.entity") public class Swagger2SpringBoot implements CommandLineRunner {
@Override public void run(String... arg0) throws Exception { if (arg0.length > 0 && arg0[0].equals("exitcode")) { throw new ExitException(); } }
... }
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 54
SeatApiController.java - findSeats() public ResponseEntity<List<SeatVO>> findSeats(@ApiParam(value = "seatNo to filter by") @RequestParam(value = "seatNo", required = false) String seatNo, @ApiParam(value = "maximum number of results to return") @RequestParam(value = "limit", required = false) Integer limit) {
List<Seat> seats = null; if(seatNo == null || seatNo.trim().length() == 0) { seats = new ArrayList<Seat>(); seatRepository.findAll().iterator().forEachRemaining(seats::add); } else { seats = seatRepository.findBySeatNoLike(seatNo); } List<SeatVO> voList = seats.stream().map(this::convertToVO).collect(Collectors.toList());
return new ResponseEntity<List<SeatVO>>(voList, HttpStatus.OK); }
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 55
Service 를 활용한 비즈니스 로직 추상화
public ResponseEntity<List<SeatVO>> findSeats(@ApiParam(value = "seatNo to filter by") @RequestParam(value = "seatNo", required = false) String seatNo, @ApiParam(value = "maximum number of results to return") @RequestParam(value = "limit", required = false) Integer limit) {
List<Seat> seats = seatService.findSeats(seatNo);
List<SeatVO> voList = seats.stream().map(this::convertToVO).collect(Collectors.toList()); return new ResponseEntity<List<SeatVO>>(voList, HttpStatus.OK);
return new ResponseEntity<List<SeatVO>>(voList, HttpStatus.OK); }
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 56
Generate Node.JS application
$ swagger-codegen generate -v -i swagger-petstore.yaml -l nodejs-server -o swagger-petstore-nodejs$ cd swagger-petstore-nodejs
$ npm start
#$ npm install #$ node index
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 57
http://localhost:8080/docs
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 58
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
HTTP API Testing FrameworkDredd
59
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 60
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 61
Supported API Descriptions Format
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 62
Supported Hooks Languages
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 63
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 64
Supported Systems (OS & CI)
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 65
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 66
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 67
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 68
run dredd with hooks file$ dredd ../swagger-msr.yaml http://localhost:8080 -f hooks.js
info: Beginning Dredd testing... info: Found Hookfiles: 0=/Users/nicholas/git/api-first-strategy/dredd/hooks.js pass: GET /api/seats duration: 80ms fail: POST /api/seats duration: 21ms pass: GET /api/seats/1 duration: 24ms fail: PUT /api/seats/1 duration: 13ms fail: DELETE /api/seats/1 duration: 23ms fail: GET /api/reservations?status=available duration: 25ms fail: POST /api/reservations duration: 16ms fail: GET /api/reservations/findByUser/1 duration: 21ms fail: GET /api/reservations/1 duration: 26ms fail: DELETE /api/reservations/1 duration: 14ms fail: PUT /api/reservations/1 duration: 17ms info: Displaying failed tests... fail: POST /api/seats duration: 21ms fail: headers: Header 'content-type' is missing
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 69
hooks.js
var hooks = require('hooks');
hooks.beforeEachValidation(function(transaction, done) { var contentType = transaction.real.headers['content-type']; console.log("#### BefereEachValidation contentType", contentType);
if(contentType === 'application/json;charset=UTF-8') { transaction.real.headers['content-type'] = 'application/json'; }
done(); });
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
How to deploy an APICloud, Docker, OnPremises
70
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 71
There are many options to deploy your API
On Premise Data Center Cloud Data Center Container
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 72
Run API on the Cloud
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 73
Polyglots
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 74
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 75
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 76
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 77
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 78
Deploy API to Docker Container
$ mvn package$ vi Dockerfile
$ docker build -t acme-msr-api:1 .$ docker run -d --name acme-msr-api -p 8080:8080 acme-msr-api:1
FROM openjdk:8-jdk-alpine COPY target/acme-msr-api-1.0.0.jar /deployments/
CMD java -jar /deployments/acme-msr-api-1.0.0.jar
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 79
Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
How to Manage an APIAPI Gateway
80
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 81
Need for an API
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 82
Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Management Service
GatewaysGatewaysGateways
APIs
Sales Cloud
ABCS
ICS
ServicesDMZ (Optional)
Cloud or On-Premise
Management PortalDeveloper Portal
Applications
Custom
On-Premise
Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Oracle Confidential – Internal/Restricted/Highly Restricted 84
One design, many instances.Centralized API Design, Distributed API Runtime
Oracle Cloud
Amazon, Azure, other
clouds
On Premises
Gateways
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 85
API Management using Policies
https://youtu.be/wN2xMjCDN6Y
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 86
Publish API using Apiary
https://youtu.be/9kF8SXcLpNI
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 87
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 88