Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

949 views

Published on

Oracle Cloud Hangout Cafe #6
人にもマシンにもやさしいAPIのエコシステム
OpenAPI,Swagger,JAX-RS,MicroProfile

Published in: Engineering
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

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

  1. 1. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 人にもマシンにもやさしい APIのエコシステム Tadahisa Kotegawa ( ) Oracle Corporation Japan May 10th, 2019 (令和元年) OCHaCafe #6 @tkotegaw
  2. 2. Copyright © 2019, 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, 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
  3. 3. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Prologue 3
  4. 4. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 4 API Ecosystem ? オレ流定義: 「クラウド上で、標準技術を使ったAPIを介して形成される、B(usiness)/C(onsumer)/G(overnment)間 の様々なバリューチェーンが、ダイナミックに遷移していくさま」
  5. 5. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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 監視 分析
  6. 6. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 人にもマシンにもやさしい APIのエコシステムを作りたい! 6
  7. 7. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 今日のトピック(ざっくり) • 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
  8. 8. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | REST API – Java で書く JAX-RS / MicroProfile 8
  9. 9. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 9 Why API by Java? Why Microservices by Java? https://www.tiobe.com/tiobe-index/ https://ochacafe.connpass.com/event/119344/
  10. 10. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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) – 2013年: JAX-RS 2.0 (JSR 339) リリース - Java EE 7 (JSR 342) – 2018年: JAX-RS 2.1 (JSR 370) リリース - Java EE 8 (JSR 366) • JAX-RS実装 – Jersey(リファレンス実装), RESTEasy, Apache CXF, etc.
  11. 11. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | JAX-RS - POJOを簡単にRESTサービスに 11 public class CountryResource { public Country getCountry(int countryId){ return CountryService.getCountry(countryId); } } @Path("/country") public class CountryResource { @GET @Path("/{countryId}") @Produces(MediaType.APPLICATION_JSON) public Country getCountry(@PathParam("countryId") int countryId){ return CountryService.getCountry(countryId); } }
  12. 12. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  13. 13. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | • 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 固有
  14. 14. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | JAX-RS – 少しだけ深堀り • Exception Mapper • Filters and Interceptors 14
  15. 15. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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 とそのサブクラス
  16. 16. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | ExceptionMapper の例 16 @GET @Path("/{countryId}") @Produces(MediaType.APPLICATION_JSON) public Country getCountry(@PathParam("countryId") int countryId) { return countryService.getCountry(countryId); } Exceptionが発生すると、どんな場合でも “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 を追加
  17. 17. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  18. 18. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | javax.ws.rs.container.ContainerRequestFilter javax.ws.rs.container.ContainerResponseFilter • 使用例: – 認証を実装する - リクエストのAuthorizationヘッダをチェック – レスポンス返信時にCORSヘッダを追加する 18 認証処理 CORS ヘッダ追加
  19. 19. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 参考: CORS (Cross Origin Resource Sharing) • 追加の HTTP ヘッダーを使用して、あるオリジン (ドメイン) で動作しているウェブアプリ ケーションに、異なるオリジンのサーバーにある選択されたリソースへのアクセスを許 可することができる仕組みです。 • セキュリティ上の理由から、ブラウザーは、スクリプトによって開始されるオリジン間 HTTP リクエストを制限しています。例えば、 XMLHttpRequestや Fetch API は同一オリ ジンポリシーに従います。つまり、これらの API を使用するウェブアプリケーションは、 そのアプリケーションが読み込まれたのと同じオリジンからのみ HTTP リソースのリク エストを行うことができ、それ以外のオリジンからの場合は正しい CORS ヘッダーを含 んでいることが必要です。 19 出展: https://developer.mozilla.org/ja/docs/Web/HTTP/CORS
  20. 20. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Name Binding 20 Name Binding用のAnnotationを定義して、FilterとリソースClass/Methodを紐付ける 基本形 CORSヘッダを 付加する CORSヘッダを 付加する Basic認証を 行う
  21. 21. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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に公開鍵ベースのシグナチャを付加して送信する必要があります
  22. 22. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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));
  23. 23. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | • 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実装
  24. 24. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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)を意味します
  25. 25. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 25 Helidonのポジショニング Full Stack MicroProfile based Microframeworks
  26. 26. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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. 27. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | デモ環境 27 Internet Me swagger-ui API Platform Java jcs home Compute apigw Compute Oracle Cloud Infrastructure swagger-editor WebLogic Server DEMO APP Apiary
  28. 28. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | デモのソース • 今日のデモのソースはこちらで入手できます。 28 https://github.com/oracle-japan/ochacafe-api-demo
  29. 29. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | (参考) 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のモジュールを追加する際はバージョンに注意
  30. 30. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | (参考)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 マニュアル操作 Oracle Cloud Infrastructure * OKE(Oracle Container Engine for Kubernetes) Tokyo DCでも 使えるよ!
  31. 31. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 31
  32. 32. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | REST API メタモデル(=仕様書)標準 戦国史 SOAPの世界は早期からWSDL一択だった… 32
  33. 33. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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 鴨長明
  34. 34. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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で記述してしまった…
  35. 35. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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で記述する特徴が 後々の展開・浸透展開の 強みになった
  36. 36. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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ドキュメンテーションに 重点を置いていた
  37. 37. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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) オープンソースだったが…
  38. 38. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  39. 39. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | (参考) OpenAPIが扱えるツールのリスト • カテゴリー – Security – Converters – Documentation – Text Editors – GUI Editors – Mock Servers – Server implementations – Miscellaneous 39 https://openapi.tools/
  40. 40. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | コード・ファースト / デザイン・ファースト 実践してみよう! 40
  41. 41. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | コード・ファースト 41 サーバー実装 を書く API仕様書 を生成する クライアント実装 を生成する / モックサーバー を提供する & etc.
  42. 42. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  43. 43. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 43 @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") @Produces(MediaType.APPLICATION_JSON) public class CountryResource { 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 @Path("/{countryId}") public Country getCountry( @Parameter(description = "国際電話の国番号 - US=1, JP=81, etc.", required = true) @PathParam("countryId") int countryId) { return countryService.getCountry(countryId); } (以下省略…)
  44. 44. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | /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: 国情報のリスト (…以下省略)
  45. 45. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Swagger UIを使ってOpenAPI Specを表示・確認する • Dockerイメージあり – サクッと試せる! • CORS対応していないリモー トのAPIを呼び出せない – ブラウザの制限によるもの (前述のとおり…) 45 https://swagger.io/tools/swagger-ui/
  46. 46. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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> <!-- when you want to generate only Models <generateApis>false</generateApis> <generateApiTests>false</generateApiTests> <generateApiDocumentation>false</generateApiDocumentation> <generateModels>true</generateModels> <generateSupportingFiles>false</generateSupportingFiles> --> </configuration> </execution> </executions> </plugin>
  47. 47. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | (参考) 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 から抜粋
  48. 48. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  49. 49. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  50. 50. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | コード・ファースト デモ • “Country” APIにSwagger Coreアノテーションをつけて、Compile/Deploy – OpenAPI Specを取得する • swagger-ui で表示、呼び出し • Swagger Codegen を使ってJava Clientソースを生成し、テストする • MicroProfile OpenAPI アノテーションからOpenAPI Specを取得する 50
  51. 51. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | デザイン・ファースト 51 API仕様 を書く サーバー実装 クライアント実装 を生成する モックサーバー を提供する & etc.
  52. 52. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Swagger Editor を使って OpenAPI仕様を書く • OpenAPI 2 & 3に対応 • スキーマの検証をやってくれる – でも流石に素から書くのは辛い… – 補助メニュー的なものはある • 各種言語のサーバー&クライアン ト ソースコードを生成&ダウン ロードが可能 52 https://swagger.io/tools/swagger-editor/
  53. 53. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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同期および統合の トラブルシューティング
  54. 54. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Apiary - OpenAPI v2(Swagger2) & v3 にも対応 54
  55. 55. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Apiaryを使ってAPI Blueprintを書いてみる 55
  56. 56. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Apiaryのモックサーバーでテストする 56 Mock Server - Mock Serverに接続しMock Serverが応答 Debugging Proxy - Proxy経由でProductionに接続し、送受信内容をデバッグする Production - Production に接続
  57. 57. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | デザイン・ファースト デモ • swagger-editor で OpenAPI形式の “Country” APIの仕様を書く • Apiary を使ってMarkdown形式の “Country” APIの仕様を書く • Apiary モックサーバーを使ったテスト 57
  58. 58. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | APIの管理 58
  59. 59. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 体系的に頭を整理したい方にお薦め (英語だけど…) 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
  60. 60. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Security Engagement Optimization APIの管理 (API Management)とは? API = 組織が持つ情報資産・サービスを外部に公開・提供するためのアクセスポイント 外部からの攻撃に 対する防御 開発者やパートナーへの 情報公開 ビジネスの最適化 • APIゲートウェイ ‒ 認証・認可 ‒ ポリシーチェック • 管理ポータル – ポリシー設定 – ライフサイクル管理 • 開発者ポータル • API利用状況、SLAの分析 • 課金・支払管理
  61. 61. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | (参考) 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
  62. 62. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | API Platform Cloud Service (APIPCS) • 任意の場所で実行可能な ハイブリッド・プラットフォーム – 管理はクラウド – Gatewayは任意の場所へ配置可能 • APIライフサイクル全体を管理 – 設計・実装・デプロイ・テスト・公開・ サブスクライブ・監視分析 • 生産性向上およびガバナンスのための 機能を提供 – API Style Guide、承認ワークフロー、Grant、 ポリシー管理、Analyticsなど 62 Deliver API for Developers and Partners
  63. 63. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 63 {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
  64. 64. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  65. 65. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | API管理 デモ API Platform Cloud Service (APIPCS) を使って • APIにポリシーを設定する • APIの利用プランを設定する • API利用者向けポータルを作る • API Keyを使ったプランの設定を試す • POSTMANを使って プランに設定されたrate limitを超えたアクセスを行う 65
  66. 66. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | デモ環境 66 Internet Me API Platform Java jcs Compute apigw Oracle Cloud Infrastructure WebLogic Server DEMO APP Apiary 管理者ポータル 開発者ポータル × API Call
  67. 67. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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. 68. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | プランとアプリケーション 68 9d2d0a62-8508-4ad9-ae1a-ab5b8659f70a e45597b0-4553-431e-9954-cecca918154c API-KEY API-KEY
  69. 69. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | APIキーの検証 69 “api-key” ヘッダを検証
  70. 70. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Epilogue 70
  71. 71. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  72. 72. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 一通りやってみての感想 • APIの”仕様と実装の一致”を維持するベスト・プラクティスは? – Javadocが成功パターンだと捉えると、APIもコードにannotationするスタイルが結局は自然と思われる • Document Writerがドキュメンテーションするような(悠長な)ライフサイクルではない筈 – MicroProfile OpenAPI の普及に期待 • 多国語サポートの仕組み (最近携わった案件で実感) – そもそもですが Internationalization は常に念頭において設計しましょう – 機械翻訳ソリューションとの組み合わせは今どきアリかも – APIエコシステムのダイナミズム! • API単発コールで物事が完結するほど単純な世の中でもない… – ステートフル、コールバック、ページネーション、etc. – オーケストレーション/コレオグラフィのメタモデルの必要性は何となく感じる… 72
  73. 73. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 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
  74. 74. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Oracle API Catalog Cloud Service 74
  75. 75. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 75

×