Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

API Design Principles Essential 

기본적인 REST API에 대한 개념과 올바른 REST API 설계를 위한 가이드를 제시합니다.

  • Identifiez-vous pour voir les commentaires

  • Soyez le premier à aimer ceci

API Design Principles Essential 

  1. 1. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 10th Oracle Developer MeetupREST API Design Principles 되새기기 이동희(DongHee Lee) Principal Solution Engineer Oracle Korea Solution Engineering
  2. 2. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3 Microservice 배포 지난 3월 16일…. 1 코드 개발 후 코드 Push 2 Wercker 빌드 후 Image 생성 3 Image를 Registry에 Push 4 Kubernetes에 배포 5 Image를 가져와서 Kubernetes 내 Container 기동 개발자 OCI Registry OCI Container Engine for Kubernetes (OKE) Wercker 서비스를 이용한 Workflow 자동화
  3. 3. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4 오늘은… 1 코드 개발 후 코드 Push 개발자
  4. 4. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 5 오늘은… 코드 개발 후 코드 Push 개발자 요건 분석 디자인 & 프로토타입 개발 Backend REST API 설계 Front-End Back-End
  5. 5. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 6 SOAP vs. REST
  6. 6. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 7 Simple Object Access Protocol vs. REpresentational State Transfer
  7. 7. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 8 SOAP: Protocol vs. REST: Architectural Style
  8. 8. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | What is REST? • 2000년, Roy Fielding의 박사 논문에서 제시된 분산 Hypermedia 시스템을 위한 아키텍처 스타일 • Guiding Principles of REST – Client–Server – Stateless – Cacheable – Uniform interface • identification of resources • manipulation of resources through representations • self-descriptive messages • hypermedia as the engine of application state – Layered system – Code on demand (optional) Confidential – Oracle Internal/Restricted/Highly Restricted 9
  9. 9. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 10 – Uniform Interface • Identification of Resources • Manipulation of Resources through Representations • Self-Descriptive Messages • Hypermedia As The Engine Of Application State
  10. 10. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 11 Resource
  11. 11. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 12 #1. Use nouns to represent resources : Resource를 명사로 표현하라.
  12. 12. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 13 첫 번째는 집합(Collection)
  13. 13. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 14 /users
  14. 14. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 15 두 번째는 단일 개체
  15. 15. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 16 /users/{userId}
  16. 16. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 17 #2. HTTP Operation를 사용하라
  17. 17. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 18 CREATE READ UPDATE DELETE
  18. 18. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 19 POST GET PUT DELETE
  19. 19. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 20 Resource POST (create) GET (read) PUT (update) DELETE (delete) /users Create new user List users Bulk Update users Delete all users /users/kildong - Get kildong Update kildong Delete kildong
  20. 20. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 21 OCI IAM Service API > User 예시 Resource POST (create) GET (read) PUT (update) DELETE (delete) /users CreateUser ListUsers - - /users/kildong - GetUser UpdateUser DeleteUser
  21. 21. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 22 추가로 필요한 조건들은 어떻게?
  22. 22. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 23 #3. 추가로 조건들은 Query Parameter를 사용하라
  23. 23. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 24 /users?title=Mr&status=active
  24. 24. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 25 /users?q={status=`active`}
  25. 25. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 26 #4. Error 메시지
  26. 26. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 27 Oracle OCI HTTP Status Code: 401 { "code": "NotAuthenticated", "message": "The required information to complete authentication was not provided or was incorrect." } FaceBook HTTP Status Code: 200 { "error": { "message": "Message describing the error", "type": "OAuthException", "code": 190, "error_subcode": 460, "error_user_title": "A title", "error_user_msg": "A message", "fbtrace_id": "EJplcsCHuLu“ } } HTTP Status Code는 항상 200, 오류 코드와 하위 오류코드 사용 Twitter HTTP Status Code: 404 { "errors": [ { "message":"Sorry, that page does not exist", "code":34 }] } HTTP Status Code중 15개 사용, 오류 코드 사용 코드 이름 조치 190 액세스 토큰이 만료됨 새 액세스 토큰을 가져옵니다. 코드 이름 설명 34 Sorry, that page does not exist Corresponds with HTTP 404. The specified resource was not found. HTTP Status Code Error Code Description 401 NotAuthenticated The required authentication information was not provided or was incorrect…
  27. 27. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 2가지 Code 사용 • HTTP Status Codes - 클라이언트 코드를 위해 사용 – 1xx (Informational): The request was received, continuing process – 2xx (Successful): The request was successfully received, understood, and accepted – 3xx (Redirection): Further action needs to be taken in order to complete the request – 4xx (Client Error): The request contains bad syntax or cannot be fulfilled – 5xx (Server Error): The server failed to fulfill an apparently valid request • Custom Error Codes – 사람을 위한 메시지 Confidential – Oracle Internal/Restricted/Highly Restricted 28 예시) OCI REST API { "code": "NotAuthenticated" or "34" "message": "The required information to complete authentication was not provided or was incorrect." }
  28. 28. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 29 #5. API 버전 관리
  29. 29. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Version • Facebook – /v3.2/{user-id}/post • Twitter – /5/accounts • Oracle PaaS: IDCS API – /admin/v1/Users/{id} • Oracle Cloud Infrastructure API – /20160918/users/ Confidential – Oracle Internal/Restricted/Highly Restricted 30
  30. 30. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 31 그 밖에 사항
  31. 31. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 32 #6. 응답 메시지는 항상 모든 것을 줄까?
  32. 32. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | 조회 칼럼 지정 • Facebook – /{your-user-id}/photos – /{your-user-id}/photos?fields=height,width Confidential – Oracle Internal/Restricted/Highly Restricted 33 { "data": [ { "created_time": "2016-08-23T13:12:10+0000", "id": "1308573619175349" // Photo ID } ] } { "data": [ { "height": 720, "width": 720, "id": "1308573619175349" // Photo ID } ] }
  33. 33. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 34 #7. Page 처리는?
  34. 34. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | List Pagination • FaceBook – offset – limit • Twitter – page – rpp (return per page) Confidential – Oracle Internal/Restricted/Highly Restricted 35
  35. 35. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | List Pagination • FaceBook – offset – limit • Twitter – count – cursor • LinkedIn – start – count Confidential – Oracle Internal/Restricted/Highly Restricted 36
  36. 36. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | List Pagination • FaceBook – offset – limit • Twitter – count – cursor • LinkedIn – start – count Confidential – Oracle Internal/Restricted/Highly Restricted 37 • Oracle PaaS API – offset – limit • Oracle Cloud Infrastructure API – page – limit
  37. 37. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Time-based Pagination • FaceBook – since – until – /me/posts?since=1364849754&until=1364587774 Confidential – Oracle Internal/Restricted/Highly Restricted 38 조회 결과의 개수가 최대 얼마나 클지를 실행 전까지는 알 수 없습니다. 질문. 직접 개발한다면, 결과를 어떤 방식으로 줄까요?
  38. 38. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 39 HATEOAS (Hypermedia As The Engine Of Application State)
  39. 39. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Hypermedia As The Engine Of Application State • FaceBook – /me/posts?offset=0&limit=2 Confidential – Oracle Internal/Restricted/Highly Restricted 40 { "data": [ { "message": "", "created_time": "2012-03-20T06:04:36+0000", "id": "" }, { "message": "", "created_time": "2012-01-19T11:26:04+0000", "id": "2700528826685328_256082517796650" } ], "paging": { "previous": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&~~~&__previous=1", "next": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&~~~~" } }
  40. 40. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Hypermedia As The Engine Of Application State • FaceBook – /me/posts?since=1298937600&until=1546300800&limit=2 Confidential – Oracle Internal/Restricted/Highly Restricted 41 { "data": [ { "message": "", "created_time": "2012-03-20T06:04:36+0000", "id": "2700528826685328_295284543876447" }, { "message": "", "created_time": "2012-01-19T11:26:04+0000", "id": "2700528826685328_256082517796650" } ], "paging": { "previous": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&since=1332223476 &format=json&access_token=~~~~&__paging_token=~~~~&__previous=1", "next": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&since=1298937600 &format=json&access_token=~~~~&until=1326972364&__paging_token=~~~~" } }
  41. 41. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 42 Store Or Association?
  42. 42. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 43 /users/{userId}/state
  43. 43. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 44 Non Resource
  44. 44. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 45 HelloWorld Translate Exchange
  45. 45. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 46 Use verb : 동사로 표현하라.
  46. 46. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 47 /translate?from=korean&to=english
  47. 47. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | • KakaoPay API Confidential – Oracle Internal/Restricted/Highly Restricted 48
  48. 48. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | • KakaoPay API Confidential – Oracle Internal/Restricted/Highly Restricted 49
  49. 49. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 50 REST API Design Principles
  50. 50. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | REST API Design Principles • #1. Resource를 명사로 표현하라 – 첫 번째는 집합(Collection), 두 번째는 단일개체 • #2. HTTP Operation를 사용하라 • #3. 추가로 조건들은 Query Parameter를 사용하라 • #4. Error 메시지는 HTTP Response Codes & Custom Error Codes • #5. API 버전 관리 – /v1/users or /20160918/users Confidential – Oracle Internal/Restricted/Highly Restricted 51
  51. 51. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 52 ## 다음 세션을 준비사항 ## - GitHub 계정 - 개인 노트북에 node.js 설치
  52. 52. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 53

×