• API Blueprint를 사용하여 API 문서를 설계하고, Oracle JET(UI Framework), Mock API, API Platform을 사용하여 프로토타입하는 과정을 실습합니다. o Designing APIs with Apiary and API Blueprint o API prototyping with Oracle JET, Mock API and API Platform

1. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1
th
김동후 (Oracle Korea)
API Design and Prototype
2019.04.20
10
th Oracle
Developer
Meetup

2. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 22
https://medium.com/better-practices/the-ultimate-api-publishers-guide-be74a2692326

3. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | 3
How to Design a Good API and Why it Matters
조슈아 블로치
소프트웨어 아키텍처
Effective Java의 저자Public APIs, like diamonds, are forever.
You have one chance to get it right so give it your best.

4. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 44https://www.programmableweb.com/api-university/understanding-api-first-design

5. 4-5배제품 출시 전 발생한 오류에 대한 해결
비용
100배제품 출시 후 유지보수 단계에서 확인된
오류에 대한 최대 해결 비용
5Copyright © 2018, Oracle and/or its affiliates. All rights reserved.
API Design이 왜 중요한가?
API-First design is a paradigm shift
Relative Costs to Fix Software Defects (Source: IBM Systems Sciences
Institute)

6. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. |
API First Design & Prototype Process
Confidential – Oracle Internal/Restricted/Highly Restricted 66

7. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. |
API First Design
Confidential – Oracle Internal/Restricted/Highly Restricted 77

8. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 88

9. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 99
https://smartbear.com/resources/ebooks/the-state-of-api-2019-report/
The State of API2019Report

10. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. |
Swagger, RAML, API Blueprint
Confidential – Oracle Internal/Restricted/Highly Restricted 1010

11. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. |
API Documentation
Confidential – Oracle Internal/Restricted/Highly Restricted 1111

12. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1212
API Blueprint 는 API Design First 접근을 위한 가장 적합한 방법

13. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1313
https://apiblueprint.org/

14. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1414
API Name and metadata

15. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1515
Resource Groups

16. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1616
Resource

17. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1717
Actions
Resource URI
URI Template or Query Parameter {?param1, param2…}
Path Parameter {param1}

18. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1818
Request > Parameters
+ key : 샘플 값 (type, optional/required) - 설명

19. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 1919
Request > Headers/Body
Content-Type 지정 (보통 PUT/POST 에서 JSON 형식으로 넘길 경우 지정)
Header 와 Header Key / Value 정의
PUT/POST 에서 JSON으로 데이터 전달할 때
JSON 형식의 샘플로 정의

20. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2020
Response > Headers/Body
Content-Type 지정 (JSON 형식으로 응답을 받는 경우)
Header 와 Header Key / Value 정의
JSON 형식 응답을 받는 경우
JSON 형식의 샘플로 정의

21. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2121
Response Without a Body

22. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2222
Attributes (Markdown Syntax Objection Notation)
각 속성은 Parameters 지정과 동일
https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md
Included MoviePeopleMeta

23. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2323
API Documentation
Mock API Url

24. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2424
API Blueprint Editors

25. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2525
Apiary

26. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2626
Vscode-apielements

27. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2727
API Prototype

28. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2828
API Prototype with API Gateway
프로토타입 UI
• API Key, OAuth, Basic Auth
• 트래픽 제어
• 단일 엔드 포인트
• 모니터링
• 로그
API Management &
Gateway
RESTful Service
Resource
RESTful Service
Resource
RESTful Service
Resource
RESTful Service
Resource

29. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 2929
API Prototype with API Gateway
API 디자인 설계
프로토타입 UI
API Mocking
• API Key, OAuth, Basic Auth
• 트래픽 제어
• 단일 엔드 포인트
• 모니터링
• 로그
API Management &
Gateway

30. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3030
API First Design & Prototype Hands-on
실습을 위한 준비 사항
• 깃헙 (https://github.com) 계정 – Apiary 계정을 만들기 위해서 필요
• Nodejs 설치 필요
• https://nodejs.org/ko/download/current/
• UI 프로토타입을 위해서 Oracle JET 설치를 위해 필요 (가급적 최신 버전)
• https://github.com/MangDan/meetup-190420-api 다운로드해서 압축 해제

31. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3131
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

32. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3232
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

33. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3333
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api
10 : ## 영화 정보 리소스 [/api/search/v1/movies]
12 : ### 영화 조회 [GET /api/search/v1/movies{?title}]
21 : + Parameters
22 : + title : 대부 (string, optional) – 제목
69 : ### 영화 상세 조회 [GET /api/search/v1/movies/{id}]
tab

34. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3434
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api
133 : # Data Structures
135 : ## MoviePeople (object)
136 : + Include MoviePeopleMeta
137 : + filmography : 쇼생크 탈출 (string, optional) - 필모그래피
139 : ## MoviePeopleMeta (object)
140 : + id : 10084614 (number, required) - 아이디
141 : + name : 프랭크 다라본트 (string, required) – 이름
142 : + role : 감독 (string, optional) - 역할
타이핑이 어려우신 분들은 1.3. API Blueprint 완성된 문서에서 복사해서 붙여넣기
하셔도 됩니다.

35. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3535
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api
116 : + Attributes (array[MoviePeopleMeta])
131 : + Attributes (MoviePeople)
tab
tab
여기까지 못 따라 오신 분들은 1.3. API Blueprint 완성된 문서 내용을 붙여넣기 하셔도 됩니다.

36. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3636
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

37. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3737
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

38. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3838
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

39. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3939
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api

40. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4040
API First Design Hands-on
https://github.com/MangDan/meetup-190420-api
UI Prototype을 위해서
Mock 서버의 호스트 정보를 확인합니다.
e.g.) http://private-df8a0-api722.apiary-mock.com

41. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4141
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
API 디자인 설계
• CORS
• api_key
API Management &
Gateway
API Mocking
두개의 보안 정책 적용

42. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4242
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
API 게이트웨이 배포
http://132.145.161.244:8011/api/search/v1

43. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4343
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
API 디자인 설계
API Mocking
• CORS
• api_key
API Management &
Gateway
http://132.145.161.244:8011/api/search/v1
endpoint

44. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4444
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
상단 meetup-190420-api 레파지토리를 클릭한 후 Clone or download 을 선택하고 Download Zip
버튼을 클릭해서 레파지토리 소스를 임의의 디렉토리에 다운로드 받고 압축을 해제합니다.

45. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4545
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
http://oraclejet.org

46. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4646
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
오라클 JET (UI) 프로젝트안으로 이동, 소스내 URL을 API Gateway의 Endpoint로 변경
(이미 적용되어 있습니다.)
• jet-movie-msa-ui/src/js/endpoints.json
{
"movies": "http://132.145.161.244:8011/api/search/v1/movies",
"image": "https://image.tmdb.org/t/p/w185"
}
• JET UI를 시작하기 위해서 Oracle JET CLI를 설치
• npm install -g @oracle/ojet-cli

47. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4747
API Prototype Hands-on
https://github.com/MangDan/meetup-190420-api
• cd jet-movie-msa-ui
• npm install @oracle/oraclejet-tooling --save
• ojet serve
http://localhost:8080

48. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4848
API First Design & Prototype

49. Copyright © 2017, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4949
다음 시간에는…

50. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
감사합니다.
Confidential – Oracle Internal/Restricted/Highly Restricted 50