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
: 뭐죠? • Resources와 Presentations은 구분되야함 • Resource는 다양한 형태(XML, JSON, HTML, PNG..) 로 표현될 수 있으며, 이를 통해서 조종되어야 합니다. Content-type: application/json http://domain/resource/1 1
As The Engine Of Application State • client는 사전지식 없이 server로부터 동적으로 제공되는 하이퍼미디어를 통해서 상호작용해야함 • 사전 정의된 interface로 통신하는 SOA와 구분 • API구현에 있어서 아직까지 Best practice는 없어보임 예제) 웹브라우저로 조작하는 웹페이지 1
한 API 설계에 핵심 • HTTP Method인 POST/GET/PUT/DELETE를 동사 대신에 사용 2-1 API 설계: 기본원칙 /getAllLeashedDogs /verifyVeterinarianLocation /feedNeededFood /createRecurringMedication
Resource에 대해서 • Collection = /dogs • Element in Collection = /dogs/123 • /dog vs /dogs ? • 1차 기본 URL은 collection이므로, /dogs가 되는 것이 더 자연스러움 2-1 API 설계: 기본원칙
• 명사를 쓰고 동시를 피하기 • POST/GET/PUT/DELETE를 동사 대신에 사용 • 직관적이고 단순하자 2-1 API 설계: 기본원칙 Resource POST = Create GET = Read PUT = Update DELETE = Delete /dogs 개 추가 개 목록보기 개 대량 갱신 개 전체 삭제 /dogs/12 에러 개 12 보기 개 12 수정 (없으면 에러) 개 12 삭제
가이드라인 • `-`,`_`를 사용합시다 • 구글에서 그렇게 권해요 • IIS는 대소문자 구분 안해요 • 사람 실수를 방지하기 좋아요 [참고] w3 URL 표준에 따르면 • domain 부분은 대소문자 구분안함 • path 부분은 반드시 대소문자 구분해야함 • IIS를 죽입시다 IIS는 나의 원수 /notions/snakes-vs-camel
가이드라인 JavaScript Object Notation • JS에선 변수에 대해서는 CamelCase 적용 • 불만은 Douglas Crockford 아저씨께 • Java로 개발하는데 SnakeCase로 하고 싶으면 • Jackson / Jaxb Annotation 도배질 필요
모두 다 잘됨: 200 OK • Client에러: 400 Bad Request • Server에러: 500 Internal Server Error 좀 더 써본다면… • 201 Created • 304 Not Mofified • 404 Not Found • 401 Unauthorized • 403 Forbidden
라이브러리의 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을 쓰면 되는데 무슨 걱정?
많이 부딪히는 문제 • /withA는 path, URI용입니다 • /withA는 명사지만, 사실상 동작 역활 • 향후에 withA, withB 등이 등장하고, 각각/조합 fetch 기능이 요구될 수 있음 2-2 API 설계: 가이드라인 /dogs/1/withA (X) /dogs/1?withA=true (O)
framework • REST를 구현하기 위한 많은 기능을 지원 • @RequestMapping • @PathVariable • @RequestParam • @RequestBody • @ResponseBody • messageConverter 3-1 API 구현하기: Spring MVC
• Annotation 중심으로 정의된 API • 따라서 다양한 구현체가 존재함 • Apache CXF: Apache software foundation 구현체 • Jersey: Sun 표준 구현체 • RESTeasy: JBoss 구현체 • Restlet • Apache Wink 3-2 API 구현하기: JAX-RS 구현
대부분의 설정/추가로직 제어 • Servlet container 없이도 동작가능 • Netty, Grizzly 등등 • 편리한 Request/ResponseBuilder • REST 관련 기술의 빠른 도입 • Gzip, Cache, Oauth, WebSocket 등 • 많은 구현체, 많은 도구들 • Swagger 문서자동화툴 3-2 API 구현하기: JAX-RS 구현
return되는 json을 잡아서 이쁘게 처리해요 • 그래서 mvn은 바이바이 standalone 아듀 4-1 API 문서화: Swagger 언젠간 될 거에요… • 이슈가 올라와서 열심히 토론 중이에요 • 언젠간 될 거에요 • 개발자가 좋은 아이디어 있으면 달라고 하네요