ochacafe#6 人にもマシンにもやさしいAPIのエコシステム

Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
人にもマシンにもやさしい
APIのエコシステム
Tadahisa Kotegawa ( )
Oracle Corporation Japan
May 10th, 2019 (令和元年)
OCHaCafe #6
@tkotegaw

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, timing, and pricing of any
features or functionality described for Oracle’s products may change and remains at the
sole discretion of Oracle Corporation.
2

Prologue
3

Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 4
API Ecosystem ?
オレ流定義：
「クラウド上で、標準技術を使ったAPIを介して形成される、B(usiness)/C(onsumer)/G(overnment)間
の様々なバリューチェーンが、ダイナミックに遷移していくさま」

Client
Application
API
Doc
今日のお題:
生活レベルの高いAPIのエコシステムを考えてみる
5
API
Mock Server
API
Production Server
API
Gateway
API
Developer Portal
API 設計者
API 実装者
API 利用管理者
API
SPEC
API GW 管理者
<<API GW管理>>
API 管理者API
SPEC
<<API利用>>
API
Management
<<ｻﾌﾞｽｸﾗｲﾌﾞ>>
<<閲覧>>
<<ﾀﾞｳﾝﾛｰﾄﾞ>><<生成>>
<<実装>>
<<APIﾃｽﾄ>>
API
Doc
<<ﾃﾞﾌﾟﾛｲ>>
<<生成>>
<<実装>>
<<生成>>
<<実装>>
<<生成>>
<<設計>>
<<実装>>
<<作成>>
<<生成>>
API
Client
Code
API
Server
Code
API 利用者
<<連携>>
<<連携>>
ﾎﾟﾘｼｰ
ｻﾌﾞｽｸﾘ
ﾌﾟｼｮﾝ
API
ｶﾀﾛｸﾞ
<<ｷｭﾚｰﾄ>>
microservices
microservices
microservices
microservices
microservices
監視
分析

人にもマシンにもやさしい
APIのエコシステムを作りたい！
6

今日のトピック（ざっくり）
• REST APIのJava実装標準について
– JAX-RS, MicroProfile, Helidon
• REST APIのメタモデル(仕様書)標準について
– WADL, RAML, API Blueprint, Swagger, OpenAPI
• REST API仕様とその実装の同期・フロースルー化について
– コード・ファースト (Swagger Core, MicroProfile OpenAPI)
– デザイン・ファースト (Apiary)
• REST APIの管理について
– API管理の動機と構成要素
– ポリシー管理、プラン＆サブスクリプション (Oracle API Platform)
7

REST API – Java で書く
JAX-RS / MicroProfile
8

Why API by Java? Why Microservices by Java?
https://www.tiobe.com/tiobe-index/
https://ochacafe.connpass.com/event/119344/

JAX-RS – The Java API for RESTful Web Services
• RESTfulを実装するAPIセット
• Plain Old Java Object（POJO）をアノテーションによって修飾
• 歴史
– Oracleがスペックリード
– 2008年: JAX-RS 1.0 (JSR 311) リリース - Java EE 6 (JSR 316)
• JAX-RS実装
– Jersey（リファレンス実装）, RESTEasy, Apache CXF, etc.

JAX-RS - POJOを簡単にRESTサービスに
11
public class CountryResource {
public Country getCountry(int countryId){
return CountryService.getCountry(countryId);
}
}
@Path("/country")
@GET
@Path("/{countryId}")
@Produces(MediaType.APPLICATION_JSON)
public Country getCountry(@PathParam("countryId") int countryId){
return CountryService.getCountry(countryId);
}
}

Eclipse MicroProfile
• Accelerating Cloud-Native Application Development with Java Microservices
– 古臭いアプリケーション開発スタイルじゃダメ！
• × monolithic, proprietary
• 〇 newer architectures and frameworks, adoption of DevOps
• 〇 speed, efficiency, and security
– Java EEのスキルや経験をMicroservicesに活かしましょう！
12
microprofile.io
E-book: https://drive.google.com/file/d/1qwCVfwjItMsvHP2xRhhArO613jp3JOvc/view
Presentation: https://drive.google.com/open?id=1KsVjbmGcZuFCtx5F7ZeCwogM6VPCC6VwwLYFQelb8H8

• MicroProfile Config 1.3
• MicroProfile Fault Tolerance 2.0
• MicroProfile Health Check 2.0
• MicroProfile JWT Authentication 1.1
• MicroProfile Metrics 2.0
• MicroProfile OpenAPI 1.1
• MicroProfile OpenTracing 1.3
• MicroProfile Rest Client 1.2
• MicroProfile Reactive Streams Operators 1.0
• CDI 2.0
• Common Annotations 1.3
• JAX-RS 2.1
• JSON-B 1.0
• JSON-P 1.1
• (Java SE 8)
13
Eclipse MicroProfile 2.2
Java EE 8 由来MicroProfile 固有

JAX-RS – 少しだけ深堀り
• Exception Mapper
• Filters and Interceptors
14

javax.ws.rs.ext.ExceptionMapper
• 通常はJAX-RSが定義しているExceptionを使え
ば、適切なレスポンス・コードを返してくれる
– javax.ws.rs.WebApplicationException 及び
そのサブクラス
• 特定のExceptionのレスポンスをカスタマイズし
たい場合に使用する
– 任意の場所で起きうる特定のExceptionをハンドリン
グして共通的なレスポンス処理を記述することが可能
になる
15
WebApplicationException
• ClientErrorException
• BadRequestException
• ForbiddenException
• NotAcceptableException
• NotAllowedException
• NotAuthorizedException
• NotFoundException
• NotSupportedException
• RedirectionException
• ServerErrorException
• InternalServerErrorException
• ServiceUnavailableException
JAX-RSが提供している
WebApplicationException
とそのサブクラス

ExceptionMapper の例
16
@GET
public Country getCountry(@PathParam("countryId") int countryId) {
return countryService.getCountry(countryId);
}
Exｃeptionが発生すると、どんな場合でも “500 Internal Server Error”
@Provider
public class CountryNotFoundExceptionMapper implements ExceptionMapper<CountryNotFoundException> {
@Override
public Response toResponse(CountryNotFoundException e) {
return Response.status(Status.NOT_FOUND).build();
}
}
CountryResource.java
CountryNotFoundExceptionMapper.java
CountryNotFoundExceptionが発生した場合には “404 Not Found”
ExceptionMapper を追加

Filters and Interceptors
• RESTメソッドの実装をラップする（or 割り込む）拡張ポイントを提供
– いわゆる「横断的関心事(Cross-cutting Concerns)」的な…
• Filters – ロギング、認証、ヘッダ追加、etc.
• Public interface ClientRequestFilter
• Public interface ClientResponseFilter
• Public interface ContainerRequestFilter
• Public interface ContainerResponseFilter
• Entity Interceptors – フォーマット変換、圧縮、etc.
• public interface ReaderInterceptor
• public interface WriterInterceptor
• Name Binding
• アノテーションを使って任意のクラス・メソッドに関連付けすることができる
17

javax.ws.rs.container.ContainerRequestFilter
javax.ws.rs.container.ContainerResponseFilter
• 使用例:
– 認証を実装する
- リクエストのAuthorizationヘッダをチェック
– レスポンス返信時にCORSヘッダを追加する
18
認証処理
CORS ヘッダ追加

参考: CORS (Cross Origin Resource Sharing)
• 追加の HTTP ヘッダーを使用して、あるオリジン (ドメイン) で動作しているウェブアプリ
ケーションに、異なるオリジンのサーバーにある選択されたリソースへのアクセスを許
可することができる仕組みです。
• セキュリティ上の理由から、ブラウザーは、スクリプトによって開始されるオリジン間
HTTP リクエストを制限しています。例えば、 XMLHttpRequestや Fetch API は同一オリ
ジンポリシーに従います。つまり、これらの API を使用するウェブアプリケーションは、
そのアプリケーションが読み込まれたのと同じオリジンからのみ HTTP リソースのリク
エストを行うことができ、それ以外のオリジンからの場合は正しい CORS ヘッダーを含
んでいることが必要です。
19
出展: https://developer.mozilla.org/ja/docs/Web/HTTP/CORS

Name Binding
20
Name Binding用のAnnotationを定義して、FilterとリソースClass/Methodを紐付ける
基本形
CORSヘッダを
付加する
CORSヘッダを
付加する
Basic認証を
行う

javax.ws.rs.client.ClientRequestFilter
• 使用例: Oracle Cloud Infrastructure の
APIの呼び出しに必要なSignatureを生
成して送信Headerに追加する
– OCI APIの署名方式はIETFのInternet Draftである
“Signing HTTP Messages”
(https://tools.ietf.org/html/draft-cavage-http-
signatures-08) に準拠
21
Authorization: Signature
keyId="ocid1.tenancy.oc1..aaaaaaaa3mb7wrcy1ls3u2jsysoq5ck4lc3q4mczitpdaymbuazc5tkguca/ocid1.user.oc1..aa
aaaaaa2nh4vgi4c4u6f3youa7srkwrfmwowniw3fkjz3bgenowlo4hsnvq/69:e6:7b:aa:73:13:d1:2f:ca:22:30:ec:21:b7:d
e:2a",algorithm="rsa-sha256",headers="date (request-target) host content-length content-type x-content-
sha256",signature="btfTH2EyKO1lfqqEcuK48J/xZkAyHTMMPhLrJ6JJI1q93mn2+VL2LTotzMX6ZE3JA4D/8xahc+2deM
3NaRL0wpX6HUc4msmfUjSfaeBcG/2PHlNa72QWHwUqu5HSQR3dM/xJH2uVvE1duj1bcTTlJlsim8Eq3t8Pw53Dg/vF
MEfmMw9wxr6QB2oc8J8k4VqV1YKpaSjdi213AP0w/aLUWcYu3ZbUxoL9a1/W5WJmRdChBteqb5rie+JOUB6h7cZeX4
dYlck+h8l3LcsU+wGvv8vJQtCo2Jy0g+pCzha4Egi5LSc5ztZnp5Uw28FXRVvqPr8Ou3HzE2dzNW/WNVRSbg=="
参考: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/signingrequests.htm
* OCIのAPIをコールする際には、Request Headerに公開鍵ベースのシグナチャを付加して送信する必要があります

JAX-RS Client for Oracle Cloud Infrastructure API
• OCI APIの呼び出し時に必要なSignatureヘッダをつける
JAX-RS Client Request Filterを作ってみました
22
https://github.com/tkote/oci-jaxrs-client
Client client = ClientBuilder.newClient();
client.register(OciJaxRsClientFilter.class);
WebTarget target = client.target("https://xxx.oci.oraclecloud.com/yyy/zzz");
Builder builder = target.request();
Response response = builder.post(Entity.entity(new SomeRequest(), MediaType.APPLICATION_JSON_TYPE));

• WebLogic Server
– ミッション・クリティカルな業務に対応
する商用アプリケーションサーバー
– Java EE 7 対応
• 次バージョンでJava EE 8 対応予定
– クラウドでも提供
• Oracle Java Cloud Service
• Project Helidon
– OSSプロジェクト
– SEとMPの2モデル
• Helidon MP: MicroProfile 1.2 (Helidon 1.0)
• Helidon SE: functional style API
23
Oracleの提供するJAX-RS実装

Project Helidon
• OSS プロジェクト
• Microservicesを開発するためのJavaライブラリの集合体
• 単体のJVMとして動作。アプリケーションサーバー不要
• 従来からの一般的なツールで開発できる(Java SE, Maven, Docker, Kubernetes, etc.)
• 2つのプログラミングモデル
– Helidon MP: 宣言的な記法、Java EE開発者フレンドリー
– Helidon SE: 関数型の記法
• Eclipse MicroProfile実装(MP)
• Oracle Cloudとのインテグレーション（将来的に実装される予定）
24
※ Helidonはギリシア語でつばめ（swallow）を意味します

Helidonのポジショニング
Full Stack
MicroProfile based
Microframeworks

JAX-RS デモ
• “Country” APIをJAX-RSベースで作成
• ExceptionMapper を使ってHTTPリターンコードを変更
• ContainerRequestFilter を使ってBasic認証をかける
• ContainerResponseFilter を使ってCORSヘッダを追加する
• ブラウザからAPIを呼び出して動作確認
• (時間があれば)同じソースをベースにHelidonアプリをDeveloper Cloud Serviceを使って
build & コンテナ化しOKE (Oracle Container Engine for Kubernetes)に載せる
26

デモ環境
27
Internet
Me
swagger-ui
API Platform
Java
jcs
home
Compute
apigw
Compute
Oracle Cloud Infrastructure
swagger-editor
WebLogic Server
DEMO APP
Apiary

デモのソース
• 今日のデモのソースはこちらで入手できます。
28
https://github.com/oracle-japan/ochacafe-api-demo

(参考) JavaEEコンテナで動作するJAX-RSリソースを
Helidon MPで動作させるには
• JAX-RSなので、基本何もソースを修正しなくても動作する
– Helidon MPはCDIを使った実装をしているので、そこだけ注意
• javax.ws.rs.core.Applicationの派生クラスに @ApplicationScoped をつける
• META-INF/beans.xml を準備する(中身は空でOK)
• Java SEで動作させるので、pom.xmlを修正
– war -> jar
– dependencies
• Helidon関連ライブラリ(bundleを使うのがとりあえず便利)
• アプリが使う依存ライブラリ（もしあれば）
29
<dependencies>
<dependency>
<groupId>io.helidon.microprofile.bundles</groupId>
<artifactId>helidon-microprofile-1.2</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-binding</artifactId>
<version>2.26</version>
</dependency>
</dependencies>
Helidon内部でJerseyを使っているので、
Jerseyのモジュールを追加する際はバージョンに注意

(参考)Helidon MPをKubernetesにデプロイする
30
Load
Balancer pods
Helidon MP
DEMO APP
Container
(OKE)
Container
Registry (OCIR)
Container
Pipelines (Werker)
container
Me
git push
Jib plugin (Maven, Gradle)
API request
Developer
Cloud Service
git push
trigger
trigger
webhook
kubectl
マニュアル操作
* OKE(Oracle Container Engine for Kubernetes)
Tokyo DCでも
使えるよ！

REST API メタモデル（=仕様書）標準戦国史
SOAPの世界は早期からWSDL一択だった…
32

API仕様標準と、それをめぐるステークホルダーたち
33
参考: A Short History of OAI and API Specifications
http://restlet.com/blog/2017/04/26/a-short-history-of-oai-and-api-specifications/
WADL
(2009)
Swagger
(2010)
API Blueprint
(2013)
RAML
(2013)
OpenAPI
(2015)
Sun
Microsystems
time
Apigee
Apiary
Mulesoft
Swagger 2.0
WG
Open API
Initiative
3Scale
Apigee
Capital One
Google
IBM
Intuit
Microsoft
Paypal
Restlet
SmartBear
よどみにうかぶうたかたは
かつ消えかつ結びて、久し
くとどまりたるためしなし。
by 鴨長明

WADL (Web Application Description Language)
• https://www.w3.org/Submission/wadl
– 「HTTPベース・アプリのI/Fを機械処理できるように記述したもの」
• Jersey (https://jersey.github.io/)
に実装されている
– WebLogic Serverもこれ
• https://github.com/javaee/wadl
にJavaコード生成ツールあり
34
<?xml version="1.0" encoding="UTF-8"?>
<ns0:application xmlns:ns0="http://wadl.dev.java.net/2009/02">
<ns0:doc xmlns:ns1="http://jersey.java.net/" ns1:generatedBy="Jersey: 2.
<ns0:doc xmlns:ns2="http://jersey.java.net/" ns2:hint="This is simplifie
<ns0:grammars>
<ns0:include href="application.wadl/xsd0.xsd">
<ns0:doc title="Generated" xml:lang="en"/>
</ns0:include>
</ns0:grammars>
<ns0:resources base="https://api.ochacafe.com/api-ochacafe/api/">
<ns0:resource path="/country">
<ns0:resource path="/cors/{countryId}">
<ns0:param name="countryId" style="template" xmlns:xsd="http:/
<ns0:method id="getCountryWithCORS" name="GET">
<ns0:response>
<ns0:representation element="country" mediaType="applica
</ns0:response>
</ns0:method>
</ns0:resource>
<ns0:resource path="/auth/{countryId}">
<ns0:param name="countryId" style="template" xmlns:xsd="http:/
<ns0:method id="getCountryWithAuth" name="GET">
<ns0:response>
JSONのスキーマを
XMLで記述してしまった…

Swagger
• https://swagger.io/
– 「ベストなAPIは Swagger Tools で作られる」
• Design – Build – Document – Test – Standardize
• JSON or YAMLで記述
35
swagger: "2.0"
info:
description: “Get Country Information"
version: "1.0.0"
host: "foobar.com"
basePath: "/api-ochacafe/api/v1"
tags:
- name: "/country"
schemes:
- "https"
paths:
/country:
get:
tags:
- "/country"
summary: "List all countries"
operationId: "getCountries"
produces:
- "application/json"
parameters: []
responses:
200:
JSONで記述する特徴が
後々の展開・浸透展開の
強みになった

API Blueprint
• https://apiblueprint.org/
– 「プロジェクト関係者間の会話と共同作業を促進する」
• Markdownを拡張した記法
36
FORMAT: 1A
HOST: http://foo.bar.com/api-sample/api/v1
# Country Information
Defines a few endpoints to retrieve country information
## Country [/country]
### List all countries [GET]
Retrieves all information as an array of Country objects
+ Response 200 (application/json)
+ Attributes (array[TCountry])
+ Response 401
`Unauthorized` - Arthorizaition failed
+ Body
利用者視点の
APIドキュメンテーションに
重点を置いていた

RAML (RESTful API Modeling Language)
• https://raml.org/
– 「APIを人が読める形式(= plain text)」で記述」
• YAMLを拡張した記法
37
#%RAML 1.0
title: Country Service
version: v1
baseUri: http://api.ochacafe.com/api/v1
types:
Country:
type: object
properties:
countryName: string
countryId: string
Countries:
type: array
items:
type: Country
/country:
displayName: /country
description: List all countries
get:
responses:
200:
body:
application/json:
type: Countries
404:
description: Country not found
Swaggerに対抗する
もう一つの解(YAML)
オープンソースだったが…

OpenAPI Specification
38
• https://www.openapis.org/
– Linux Foundation に Open API Initiative が発足(2015)
– v2 (= Swagger 2.0) と v3 (https://github.com/OAI/OpenAPI-Specification)
• v3 → 構造をシンプルに、コンポーネント化・再利用、マルチホスト、他
出典: https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2
識別子
swagger: 2.0
識別子
openapi: 3.0.x

(参考) OpenAPIが扱えるツールのリスト
• カテゴリー
– Security
– Converters
– Documentation
– Text Editors
– GUI Editors
– Mock Servers
– Server implementations
– Miscellaneous
39
https://openapi.tools/

コード・ファースト / デザイン・ファースト
実践してみよう！
40

コード・ファースト
41
サーバー実装
を書く
API仕様書
を生成する
クライアント実装
を生成する /
モックサーバー
を提供する & etc.

Swagger Coreを使ってOpen APIドキュメントを取得する
• JAX-RSのJavaソースコードにAnnotationをつける
– AnnotationはSwagger Core仕様
• io.swagger.v3.oas.annotations パッケージ
• 必要なライブラリをプロジェクトに追加
– Mavenの<dependency>を追加
• web.xmlにサーブレットを追加
– io.swagger.v3.jaxrs2.integration.OpenApiServlet
• このサーブレットがランタイムでOpen APIドキュメントを提供する
– Annotationにダブルバイト使うとAPIドキュメントに文字化け(ブラウザ)発生 orz
• 自力でサーブレット修正(Content-type: application/json; charset=utf-8)
42
https://github.com/swagger-api/swagger-core

@OpenAPIDefinition(
info = @Info(title = "Open API アノテーションサンプル", version = "1.0",
description = "コード・ファーストでAPIを実装し、アノテーションを付加してOpen API仕様のドキュメントを出力するサンプルです",
license = @License(name = "Oracle Japan", url = "http://www.oracle.com"),
contact = @Contact(name = "Tad Kotegawa")),
servers = { @Server(url = "http://jcs.ochacafe.kotegawa.com/api-ochacafe/api/v1") })
@Tag(name = "/country", description = "国情報の提供")
@Path("/country")
private CountryService countryService = new CountryService();
public CountryResource() {}
@Operation(summary = "List all countries", description = "保持している全ての国情報のリストを取得します",
responses = {
@ApiResponse(responseCode = "200", description = "国情報のリスト",
content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = Country.class)))),
@ApiResponse(responseCode = "401", description = "認証に失敗しました"), })
@GET
@Path("/")
public Country[] getCountries() throws Exception {
return countryService.getCountries();
}
@Operation(summary = "Find country by country code", description = "国コードから国情報を検索します",
responses = {
@ApiResponse(responseCode = "200", description = "国情報",
content = @Content(mediaType = "application/json", schema = @Schema(implementation = Country.class))),
@ApiResponse(responseCode = "401", description = "認証に失敗しました"),
@ApiResponse(responseCode = "404", description = "指定した国コードから国情報が見つかりませんでした") })
@GET
public Country getCountry(
@Parameter(description = "国際電話の国番号 - US=1, JP=81, etc.", required = true) @PathParam("countryId") int countryId) {
return countryService.getCountry(countryId);
}
(以下省略…)

/openapi にアクセスする
44
リクエストのAccept: header (application/json or application/yaml)で返ってくるメディアタイプを制御可能
openapi: 3.0.1
info:
title: Open API アノテーションサンプル
description: コード・ファーストでAPIを実装し、アノテーションを付加してOpen API仕様のドキュメントを出力するサンプルです.
contact:
name: Tad Kotegawa
license:
name: Oracle Japan
url: http://www.oracle.com
version: "1.0"
servers:
- url: http://jcs.ochacafe.kotegawa.com/api-ochacafe/api/v1
variables: {}
tags:
- name: /country
description: 国情報の提供
paths:
/country:
get:
tags:
- /country
summary: List all countries
description: 保持している全ての国情報のリストを取得します
operationId: getCountries
responses:
200:
description: 国情報のリスト
(…以下省略)

Swagger UIを使ってOpenAPI Specを表示・確認する
• Dockerイメージあり
– サクッと試せる！
• CORS対応していないリモー
トのAPIを呼び出せない
– ブラウザの制限によるもの
（前述のとおり…）
45
https://swagger.io/tools/swagger-ui/

Swagger Codegen を使ってClient ソースを生成する
• とりあえずJava Client
• Maven Plugin を使う
– swagger-codegen-maven-plugin
• pom.xmlにpluginを追加して
“mvn generate-sources”
– target/generate-sources/swagger
ディレクトリ配下にソース一式と
Maven / Gradle のファイルができる
– “mvn test” で最低限のテスト可能
• デフォルトでテストクラスに@Ignoreが付いている
ので、これを外さないと実行されない…
46
https://github.com/swagger-api/swagger-codegen
<plugin>
<groupId>io.swagger.codegen.v3</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>3.0.7</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/openapi/openapi.yaml</inputSpec>
<language>java</language>
<configOptions>
<sourceFolder>src/main/java</sourceFolder>
</configOptions>

</configuration>
</execution>
</executions>
</plugin>

(参考) Swagger Codegen で生成できるもの
• API clients: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5,
Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x,
OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-
assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-
C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-
httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Server stubs: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J,
Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim,
Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-
server), Scala (Finch, Lagom, Scalatra)
• API documentation generators: HTML, Confluence Wiki
• Configuration files: Apache2
• Others: JMeter
47
https://github.com/swagger-api/swagger-codegen から抜粋

MicroProfile OpenAPI
• JAX-RS + MP OpenAPI Annotationで OpenAPI v3ドキュメントを生成
– org.eclipse.microprofile.openapi.annotations パッケージ
• アノテーションの多くはSwagger Core libraryに由来
48
https://github.com/eclipse/microprofile-open-api
@GET
@Path("/findByStatus")
@Operation(summary = "Finds Pets by status",
description = "Multiple status values can be provided with comma separated strings")
public Response findPetsByStatus(...) { ... }
/pet/findByStatus:
get:
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
operationId: findPetsByStatus
Java Source
OpenAPI Spec

Swagger → MicroProfile Annotation に変更してみる
• Mavenのdependencyを変更
– org.eclipse.microprofile.openapi:microprofile-openapi-api:1.0.1
• Annotation を変更
– だいたい同じ構造と名前
• importするパッケージを変えるだけでOKなものが多い
• mvn package → warを作成
• MicorProfile OpenAPI をサポートするサーバーにデプロイ
• 今回は Payara Micro で試行
• /openapi にアクセスして、OpenAPI Specをゲット
49

コード・ファーストデモ
• “Country” APIにSwagger Coreアノテーションをつけて、Compile/Deploy – OpenAPI
Specを取得する
• swagger-ui で表示、呼び出し
• Swagger Codegen を使ってJava Clientソースを生成し、テストする
• MicroProfile OpenAPI アノテーションからOpenAPI Specを取得する
50

デザイン・ファースト
51
API仕様
を書く
サーバー実装
クライアント実装
を生成する
モックサーバー
を提供する
& etc.

Swagger Editor を使って OpenAPI仕様を書く
• OpenAPI 2 & 3に対応
• スキーマの検証をやってくれる
– でも流石に素から書くのは辛い…
– 補助メニュー的なものはある
• 各種言語のサーバー&クライアン
トソースコードを生成＆ダウン
ロードが可能
52
https://swagger.io/tools/swagger-editor/

Oracle の提供するAPIソリューション - Apiary
• Oracle Apiary
• APIARY Editor
• 対話的ドキュメント化
• モック・サーバー
• API Inspector
• GitHub同期
• GitHub統合
• 自動テスト
Copyright © 2018, Oracle and/or its affiliates. All rights reserved. 53
• Apiary CLI
• GitHub Enterprise（GHE）統合
• 統合コード・サンプル
• 組み込み文書
• APIスタイル・ガイド
• GitHub同期および統合の
トラブルシューティング

Apiary - OpenAPI v2(Swagger2) & v3 にも対応
54

Apiaryを使ってAPI Blueprintを書いてみる
55

Apiaryのモックサーバーでテストする
56
Mock Server - Mock Serverに接続しMock Serverが応答
Debugging Proxy - Proxy経由でProductionに接続し、送受信内容をデバッグする
Production - Production に接続

デザイン・ファーストデモ
• swagger-editor で OpenAPI形式の “Country” APIの仕様を書く
• Apiary を使ってMarkdown形式の “Country” APIの仕様を書く
• Apiary モックサーバーを使ったテスト
57

APIの管理
58

体系的に頭を整理したい方にお薦め (英語だけど…)
59
API Management:
An Architect's Guide to Developing and Managing APIs for Your Organization
by Brajesh De
Publisher: Apress
Release Date: March 2017
ISBN: 9781484213056

Security Engagement Optimization
APIの管理 (API Management)とは？
API = 組織が持つ情報資産・サービスを外部に公開・提供するためのアクセスポイント
外部からの攻撃に
対する防御
開発者やパートナーへの
情報公開
ビジネスの最適化
• APIゲートウェイ
‒ 認証・認可
‒ ポリシーチェック
• 管理ポータル
– ポリシー設定
– ライフサイクル管理
• 開発者ポータル
• API利用状況、SLAの分析
• 課金・支払管理

(参考) API Gateway Pattern (デザインパターンとしてのAPI GW)
• clientとmicroservicesの境界を定義
• microservicesのロケーションの隠蔽（エンドポイント仮想化）
• clientの特性に合わせたAPIの提供(Backend for Frontend)
• clientからのcall数の削減/client実装の軽量化
• clientに標準プロトコルによるアクセス(REST I/F)を提供
• 横断的な関心事(cross-cutting concerns)の実装
– SSL, 認証, キャッシュ, ポリシー, QoS, ログ, etc.
61
client A
client B
microservice 1
microservice 2
microservice 3
AS-IS
microservices
API Gateway Pattern
client A
client B
microservice 1
microservice 2
microservice 3
microservices
API Gateway
Variation: Backend for Frontend (BFF)
client A
client B
microservice 1
microservice 2
microservice 3
API Gateway
API Gateway
microservices

API Platform Cloud Service (APIPCS)
• 任意の場所で実行可能な
ハイブリッド・プラットフォーム
– 管理はクラウド
– Gatewayは任意の場所へ配置可能
• APIライフサイクル全体を管理
– 設計・実装・デプロイ・テスト・公開・
サブスクライブ・監視分析
• 生産性向上およびガバナンスのための
機能を提供
– API Style Guide、承認ワークフロー、Grant、
ポリシー管理、Analyticsなど
62
Deliver API for Developers and Partners

{APIs, Policies}
定期的に
アウトバウンドリクエスト
Developer
Portal
API管理者
API実装者
Gateway管理者
{Analytics}
APIデザイナー
API利用者Management
Portal
{request}
{response}
Firewall/Load Balancer
Gatewayアプリケーション
{request}
{response}
Apiary
Design Portal
Management Service
Backend
Service

APIPCS のポリシー設定
64
セキュリティトラフィック管理インターフェース管理ルーティングその他
•OAuth 2.0
•Basic Auth
•Key Validation
•IP Filtering
•CORS
•API Rate Limiting
•API Rate Limiting Per
Application
•API Throttling
•Interface Filtering
•Method Mapping
•Field Redaction
•Header Validation
•REST to SOAP
•Header Based
•Resource Based
•Application Based
•Gateway Based
•Groovy Script
•Service Callout
•Logging

API管理デモ
API Platform Cloud Service (APIPCS) を使って
• APIにポリシーを設定する
• APIの利用プランを設定する
• API利用者向けポータルを作る
• API Keyを使ったプランの設定を試す
• POSTMANを使ってプランに設定されたrate limitを超えたアクセスを行う
65

デモ環境
66
Internet
Me
API Platform
Java
jcs
Compute
apigw
WebLogic Server
DEMO APP
Apiary
管理者ポータル
開発者ポータル
×
API Call

APIPCS: Application - Plan - API の関係
67
Application Plan
API
- Policy
- Gateway
- Documentation
* *
Entitlement (資格)Subscription
- API Key - Constraints
• API Level (rate limit)
• Action Level (rate limit)
( API利用者に払い出し )

プランとアプリケーション
68
9d2d0a62-8508-4ad9-ae1a-ab5b8659f70a
e45597b0-4553-431e-9954-cecca918154c
API-KEY
API-KEY

APIキーの検証
69
“api-key” ヘッダを検証

Epilogue
70

Client
Application
API
Doc
本日やったことのおさらい
71
API
Mock Server
API
Production Server
API
Gateway
API
Developer Portal
API 設計者
API 実装者
API 利用管理者
API
SPEC
API GW 管理者
<<API GW管理>>
API 管理者API
SPEC
<<API利用>>
API
Management
<<ｻﾌﾞｽｸﾗｲﾌﾞ>>
<<閲覧>>
<<ﾀﾞｳﾝﾛｰﾄﾞ>><<生成>>
<<実装>>
<<APIﾃｽﾄ>>
API
Doc
<<ﾃﾞﾌﾟﾛｲ>>
<<生成>>
<<実装>>
<<生成>>
<<実装>>
<<生成>>
<<設計>>
<<実装>>
<<作成>>
<<生成>>
API
Client
Code
API
Server
Code
API 利用者
<<連携>>
<<連携>>
ﾎﾟﾘｼｰ
ｻﾌﾞｽｸﾘ
ﾌﾟｼｮﾝ
API
ｶﾀﾛｸﾞ
<<ｷｭﾚｰﾄ>>
microservices
microservices
microservices
microservices
microservices
監視
分析
APIPCS
Swagger
MicroProfile
APIPCS
APIPCS
Swagger
Apiary
Apiary
Swagger
JAX-RS
APIPCS JCS (Java EE)
APIPCS
Helidon on OKE(MP)
Swagger
Apiary
JAX-RS
Client

一通りやってみての感想
• APIの”仕様と実装の一致”を維持するベスト・プラクティスは？
– Javadocが成功パターンだと捉えると、APIもコードにannotationするスタイルが結局は自然と思われる
• Document Writerがドキュメンテーションするような（悠長な）ライフサイクルではない筈
– MicroProfile OpenAPI の普及に期待
• 多国語サポートの仕組み (最近携わった案件で実感)
– そもそもですが Internationalization は常に念頭において設計しましょう
– 機械翻訳ソリューションとの組み合わせは今どきアリかも – APIエコシステムのダイナミズム！
• API単発コールで物事が完結するほど単純な世の中でもない…
– ステートフル、コールバック、ページネーション、etc.
– オーケストレーション/コレオグラフィのメタモデルの必要性は何となく感じる…
72

APIを中心とした新しいEnterprise IT Platform
73
マイクロサービスDatabaseメインフレーム ERP, Applications
SOA/Service Bus (既存システムへの接続性)
API Gateway 汎用 (IT) APIs
iPaaS （データ変換/フォーマット変換）
公開/固有 (Business) APIsAPI Gateway
Web & モバイル
アプリ
コミュニティ顧客、3rd Party
開発パートナー
SaaS パートナーSaaS
IdM
ディレクトリ
Reliable AgileBimodal IT
ITIT/Partners
ID管理
認証
認可
SSO
Federation

Oracle API Catalog Cloud Service
74

ochacafe#6 人にもマシンにもやさしいAPIのエコシステム

ochacafe#6 人にもマシンにもやさしいAPIのエコシステム

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to ochacafe#6 人にもマシンにもやさしいAPIのエコシステム

Similar to ochacafe#6 人にもマシンにもやさしいAPIのエコシステム (20)

More from オラクルエンジニア通信

More from オラクルエンジニア通信 (20)

ochacafe#6 人にもマシンにもやさしいAPIのエコシステム