API First Strategy · • 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

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


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


Open API Initiative & SpecificationOAI OAS

5


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


MuleSoft Joins the OpenAPI Initiative: The End of the API Spec Wars


Open API and RAML: Better Together






How to Design an APISwagger, API Blueprint, RAML

13


Transform API Descriptions https://apimatic.io/transformer

https://apimatic.io/transformer


Apiary supports Swagger



API Blueprint Editor


Swagger Editor


Validate API Spec


Preview


Github Integration


API Documentation


TEST through Mock Server


TEST through production Server


Request / Response Header


Response Data


Generate Client Source (Code Snippet)cURL, Java, Javascript, Node.JS, Perl, Python, PHP, Ruby, Go, C#, Visual Basic, Groovy, Object-C, Swift

27



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>


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

}}




Generate Server (eg, spring boot)



Generate Client (eg, java client)



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



Transform API Descriptions to formats of your choice






How to Develop an APISwagger Codegen

44


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)


• 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

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#erlang

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#nodejs

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#php-lumen

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#php-slim

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#php-silex

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#python-flask-connexion

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#python2-flask-connexion

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#ruby-on-rails-5

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#ruby-sinatra

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#scala-scalatra

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#haskell-servant

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#aspnet-core-10

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#go-server

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#nancyfx-module

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-jax-rs-20-spec

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-jax-rs-jersey

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-jax-rs-apache-cxf-2--3

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-jax-rs-resteasy

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-jax-rs-apache-cxf-framework-on-java-ee-server-supporting-cdi



https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-spring-mvc

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-springboot

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-undertow

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-msf4j


• 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


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


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



http://localhost:8080/api/swagger-ui.html


http://localhost:8080/api/api-docs (api-docs.json)

http://localhost:8080/api/api-docs


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(); } }

... }


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); }


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); }


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


http://localhost:8080/docs



HTTP API Testing FrameworkDredd

59



Supported API Descriptions Format


Supported Hooks Languages



Supported Systems (OS & CI)





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

http://localhost:8080


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(); });


How to deploy an APICloud, Docker, OnPremises

70


There are many options to deploy your API

On Premise Data Center Cloud Data Center Container


Run API on the Cloud


Polyglots






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



How to Manage an APIAPI Gateway

80


Need for an API



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


API Management using Policies

https://youtu.be/wN2xMjCDN6Y


Publish API using Apiary

https://youtu.be/9kF8SXcLpNI



Documents

API First Strategy · • 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