6 1-1 Client-Server REST API : 뭐죠? • 관심사의 분리(Separation of concerns) 원칙 하의 CS 구조 • 데이터 저장은 Server에서, UI는 Client에서 • 다양한 platform에 대한 이식성 향상 • 서버 컴포넌트의 단순화를 통한 확장성 향상 1
1 1 1-4 Uniform interface REST API : 뭐죠? Content-type: application/json GET http://domain/resource/1 • 통일된 URI 접근과 제한된 메소드 인터페이스로 통신 • 주요 4개 제한 조건은 아래와 같음 • identification of resource • manipulation of resources through representations • self-descriptive message • hypermedia as the engine of application state 1
1 2 1-4-1 Identification of resource REST API : 뭐죠? • REST에서 정보는 resource고, resource는 반드시 유일한 구분자(URI)를 가져야함 • 웹 기반 REST에서는 resource 접근에 URL 사용 http://domain/resource/1 1
1 3 1-4-2 manipulation of resources through representations REST API : 뭐죠? • Resources와 Presentations은 구분되야함 • Resource는 다양한 형태(XML, JSON, HTML, PNG..) 로 표현될 수 있으며, 이를 통해서 조종되어야 합니다. Content-type: application/json http://domain/resource/1 1
1 4 1-4-3 Self-descriptive Message REST API : 뭐죠? • 각 메세지들은 반드시 Task를 완료하는데 충분한 정보를 가지고 있어야 합니다. • 웹 기반 REST에서는 Method, Header 활용 Content-type: application/json GET http://domain/resource/1 1
1 5 1-4-4 HATEOAS REST API : 뭐죠? REST APIs must be hypertext-driven Ray T. Fielding, 2008 http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven 1
1 6 1-4-4 HATEOAS REST API : 뭐죠? • Hypermedia As The Engine Of Application State • client는 사전지식 없이 server로부터 동적으로 제공되는 하이퍼미디어를 통해서 상호작용해야함 • 사전 정의된 interface로 통신하는 SOA와 구분 • API구현에 있어서 아직까지 Best practice는 없어보임 예제) 웹브라우저로 조작하는 웹페이지 1
1 7 1-5 Layered System 1 REST API : 뭐죠? • Client는 직접 최종서버에 붙었는지 아니면 intermediary 서버에 붙었는지 등을 알 수 없음 • intermediary 서버 등을 통해서 로드밸런싱 / 공유캐시 등을 통해 확장성과 보안을 향상 가능
2 2 2-1 명사를 쓰고 동사를 피하자 • 실용적인 ‘RESTful’ 한 API 설계에 핵심 • HTTP Method인 POST/GET/PUT/DELETE를 동사 대신에 사용 2-1 API 설계: 기본원칙 /getAllLeashedDogs /verifyVeterinarianLocation /feedNeededFood /createRecurringMedication
2 3 2-2 Resource 당 2개의 기본 URL 사용 • Resource에 대해서 • Collection = /dogs • Element in Collection = /dogs/123 • /dog vs /dogs ? • 1차 기본 URL은 collection이므로, /dogs가 되는 것이 더 자연스러움 2-1 API 설계: 기본원칙
2 4 2-3 종합 • Resource 당 2개 기본 URL • 명사를 쓰고 동시를 피하기 • POST/GET/PUT/DELETE를 동사 대신에 사용 • 직관적이고 단순하자 2-1 API 설계: 기본원칙 Resource POST = Create GET = Read PUT = Update DELETE = Delete /dogs 개 추가 개 목록보기 개 대량 갱신 개 전체 삭제 /dogs/12 에러 개 12 보기 개 12 수정 (없으면 에러) 개 12 삭제
2 6 1 URL 표기법 – SnakeCase 2-2 API 설계: 가이드라인 • `-`,`_`를 사용합시다 • 구글에서 그렇게 권해요 • IIS는 대소문자 구분 안해요 • 사람 실수를 방지하기 좋아요 [참고] w3 URL 표준에 따르면 • domain 부분은 대소문자 구분안함 • path 부분은 반드시 대소문자 구분해야함 • IIS를 죽입시다 IIS는 나의 원수 /notions/snakes-vs-camel
3 0 3-2 HttpStatusCode • 왠만하면 Http Status Code를 활용합시다 • 다 쓰는 건 교조적, 약 10개 미만으로 선정 사용 2-2 API 설계: 가이드라인 • 모두 다 잘됨: 200 OK • Client에러: 400 Bad Request • Server에러: 500 Internal Server Error
3 1 3-3 HttpStatusCode extend 2-2 API 설계: 가이드라인 • 모두 다 잘됨: 200 OK • Client에러: 400 Bad Request • Server에러: 500 Internal Server Error 좀 더 써본다면… • 201 Created • 304 Not Mofified • 404 Not Found • 401 Unauthorized • 403 Forbidden
3 4 4-2 Versioning 예제 • URL의 prefix로 사용 • 번호는 반드시 1,2,3… 정수로만 증가 • 쉽고 간단하고, Spring MVC에서 처리도 쉬움 • @RequestMapping을 class에 달아 처리 2-2 API 설계: 가이드라인 /v1/dogs
3 7 6-2 DateTime 2-2 API 설계: 가이드라인 언어별 JSON 라이브러리의 Date 기본표현 ASP.NET 2013-05-29T15:22:30.9000000Z Json.NET2013-05-29T15:22:30Z Jackson 1369808550900 Gson May 29, 2013 3:22:30 PM JavaScript 2013-05-29T15:22:30.900Z Python 2013-05-29T15:22:30.900000 Objective C 2013-05-29T15:22:30+09:00 … 국제표준 ISO 8601을 쓰면 되는데 무슨 걱정?
4 0 6-4 DateTime 결론 2-2 API 설계: 가이드라인 UnixTime UTC • 구세주의 등장 • 1970-01-01T00:00:00Z 이후 milisec • 너무 단순해서 이견이 나올 수 없음 • library/언어에서 똑같은 결과값을 쉽게 추출 • Jackson은 이게 기본!! 진리의 Jackson
4 2 7 ORM Lazy 친구들 • Hibernate를 사용할 때 많이 부딪히는 문제 • /withA는 path, URI용입니다 • /withA는 명사지만, 사실상 동작 역활 • 향후에 withA, withB 등이 등장하고, 각각/조합 fetch 기능이 요구될 수 있음 2-2 API 설계: 가이드라인 /dogs/1/withA (X) /dogs/1?withA=true (O)
4 4 9 Login • login은 명사지만, 동사로 사용되고 있음 • login과정 자체도 결과적으로 상태를 추가 • 결과를 주어로 잡고 주어에 대한 동사를 선택 2-2 API 설계: 가이드라인 POST /login (X) POST /users/login (△) POST /session (O)
4 6 1 Spring MVC • Spring MVC는 범용 Web framework • REST를 구현하기 위한 많은 기능을 지원 • @RequestMapping • @PathVariable • @RequestParam • @RequestBody • @ResponseBody • messageConverter 3-1 API 구현하기: Spring MVC
5 2 1 JAX-RS • RESTful 웹서비스를 위한 Java AP • Annotation 중심으로 정의된 API • 따라서 다양한 구현체가 존재함 • Apache CXF: Apache software foundation 구현체 • Jersey: Sun 표준 구현체 • RESTeasy: JBoss 구현체 • Restlet • Apache Wink 3-2 API 구현하기: JAX-RS 구현
5 7 2 Why JAX-RS annotation • 단순함 • @Provider로 대부분의 설정/추가로직 제어 • Servlet container 없이도 동작가능 • Netty, Grizzly 등등 • 편리한 Request/ResponseBuilder • REST 관련 기술의 빠른 도입 • Gzip, Cache, Oauth, WebSocket 등 • 많은 구현체, 많은 도구들 • Swagger 문서자동화툴 3-2 API 구현하기: JAX-RS 구현
7 1 장점 • 개발과정에서 API 버그 찾기가 매우 편함 • 비교적 문서가 항상 최신으로 유지 가능 • 코드에 문서가 포함되어 있으므로 직관적 4-1 API 문서화: Swagger 단점 • 사실 wiki용은 안 이뻐서 스샷 안찍음 • 소소하게 안되는 부분이 있음 하지만 대부분 issue 발행되어 개발진행 중 그리고…
7 4 Swagger-spring-mvc 있잖아요 • Spring MVC를 실제로 띄워서 runtime에 return되는 json을 잡아서 이쁘게 처리해요 • 그래서 mvn은 바이바이 standalone 아듀 4-1 API 문서화: Swagger 언젠간 될 거에요… • 이슈가 올라와서 열심히 토론 중이에요 • 언젠간 될 거에요 • 개발자가 좋은 아이디어 있으면 달라고 하네요
mugi_uno
3150
seike460
prof18
blueswen
ryounasso
kamilahsantos
mot_techtalk
ivanova1991
morux2
tanakahisateru
ivargrimstad
erikaheidi
addyosmani
jensimmons
cherdarchuk
quramy
pauljervisheath
rmw
3n
mongodb
zenorocha
malarkey
keithpitt