APIs: Application Programming Interface
--------------------------------------
1. HTTP
- **HTTP is request / response**
- HTTP Primer
- URLs
- 
- protocol
- host
- port
- resource path
- query
- Header : key value
- Body : details
- HTTP Verbs
- GET : collection 이나 individual resource 획득, 생성에 관여해서는 안된다
- POST : 새로운 resource 생성
- PUT : 생성된 resource 에 대한 변경
- DELETE : 생성된 collection / resource 에 대한 삭제
- **PATCH** : PUT 과 유사하나 일부 속성을 변경할 때 주로 사용됨
- HTTP Response Code
- 2xx : SUCCESS에 관한 코드
- 200 : ok
- 201 : created
- 202 : accepted
- 204 : no content (주로 delete API 에 사용한다)
- 4xx : CLIENT_ERROR에 관한 코드 (요구 메시지가 처리할 수 없을 때)
- 400 : bad request
- 401 : unauthorized
- 403 : forbidden
- 404 : Not found
- 5xx : SERVER_ERROR에 관한 코드 (서버가 요청을 처리하는 과정에서 문제발생)
- 500 : Internal Server Error
- [reference](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
2. REST: REpresentational Statue Transfer
- 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식
- 특징
- Uniform Interface (Loose Coupling):
- 아키텍처를 단순화시키고 작은 단위로 분리(decouple)함
- 클라이언트-서버의 각 파트가 독립적으로 개선 가능
- Client / Server 구조: 일관적인 인터페이스로 분리되어야 한다
- Stateless: 각 요청 간 Client 의 context 가 서버에 저장되어서는 안 된다 ( == 구현이 단순해진다 )
- Cacheable: WWW 에서와 같이 Client 는 response 을 caching 할 수 있어야 한다
- 클라이언트-서버 간 상호작용을 부분적으로 또는 완전하게 제거하여 scalability 및 성능 향상
- Layered System: Client 는 REST API 서버만 호출한다
- Server 내부에 다중 계층을 구성하여 로드 밸런싱, 공유 캐시, 인증, 비즈니스 을 나누어 관리할 수 있다
- --------------------------------------------
- Code on demand (optional): 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트가 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있다
- 고려사항
- **transcation: 연속적 API 호출에 대한 트랜잭션을 보장하지 않는다**
- **Idempotent**
- API 호출 실패에 대한 구체적인 명시가 필요하다
- 필요의 경우, 보상 트랜잭션의 구현이 필요하다
- **실패에 대한 처리: 예외코드 / 예외메시지 를 제공한다**
- client 의 조치가 필요한 케이스
- retry / restart 등의 조치
- server 의 조치가 필요한 케이스
3. API 모델링 및 디자인
- API 모델링 steps
- step1 : Identify participants
- 사용할 object 단위로 정의해라?
ex) system admin, customer, manager etc ...
- step2 : Identify Activities
- object 들의 동작과 동작결과를 정의해라? : 한줄정도 요약
- step3 : Break Into Steps
- 동작을 쪼개어 순서대로 정의해라 : 요약된 한줄의 동작을 수행하는 단계를 정의
- step4 : Create Resource API Definitions
- 각 단계 에서 필요한 items 들을 정의해라
- 힌트 :
- 일반적인 개념과 같은 그룹
- db 테이블에서 사용하는 properties 가 될 수 있다
- step5 : Validate API
- API 디자인 steps
- step1. Ontology 구성
- 클래스(class), 인스턴스(instance), 관계(relation), 속성(property)
- step2. 구성원들간의 관계 정의
- Independent : 독립적으로 존재
- Dependent: 부모 resource 의 존재에 의해 생성 가능한 존재
- Associative: 독립적인 존재이지만, ...
- step3. HTTP 규격에 맞게 정의하기
- method: CRUD
- URL: 구성원
- response: API 수행결과
- step4. 프로토 타입 공유
- 실습
story : As a customer, I want to order a coffee so that the coffee shop can prepare my drick 1. modeling exercise - step1 : Identify participants Customer, waitress, Barista - step2 : Identify Activities Order | Customer, waitress | Prepare Coffee | Barista | - step3 : Break Into Steps Order Select Menu | Customer Order | Customer Confirm Order | Customer, waitress Prepare Coffee Confirm Order | Barista Make Coffee | Barista - step4 : Find Resources Order menu list, menu detail Make Coffee ingredient - step5 : Validate API Order - Select menu list API | Customer, waitress - Create Order API | waitress - Confirm Order API | Customer, waitress Make Coffee - Get Order API | Barista - Make Coffee | Barista 2. design exercise Order - Select menu list API GET /menu | 200 OK , 500 Internal Server Error - Create Order API POST /order | 201 Created , 204 No Content , 400 Bad Request , 500 Internal Server Error - Confirm Order API POST /order/{order_id} | 200 OK , 500 Internal Server Error Make Coffee - Confirm Order API GET /order/{order_id} | 200 OK , 404 Not Found , 500 Internal Server Error - Make Coffee POST /coffee/ | 201 Created , 204 No Content , 500 Internal Server Error |
4. 훌륭한 API 의 7가지 특징
- #1. Greate APIs "Just Work": 직관적이고 예측 가능해야한다
- #2. Greate APIs are Interactive (대화)
- Documentation is great
- Interactive documentation is better (like JAVA DOC) >> swagger 가 유용하다
- #3. Greate APIs have Examples
- should be short
- something useful
- simple and complex use case
- #4. Greate APIs are Considerate 신중한, 주의 깊은
- protocol 과 payload 를 쉽게 사용할 수 있도록 선택해야 한다
- ex) REST vs SOAP, JSON vs XML
- [REST와 SOAP비교] (http://greatkim91.tistory.com/79)
- #5. Greate APIs are Adoptable 채용
- 쉽게 호할 수 있도록
- high value for 비즈니스
- low pain for 통합/유지보수
- #6. Greate APIs offer Variation in Granularity
- 3 레벨
- access APIs ( row한 의 API )
- workflow APIs ( 상위레벨의 API )
- SDK APIs ( 개발 언어별로 )
- #7. Greate APIs are Consistent
- name, design, error handle, massage
