서비의 다락방

한빛 미디어의 e-book "일관성 있는 웹 서비스 인터페이스 설계를 위한 REST API 디자인 규칙" 의 목차에서 추려낸 REST API 디자인 규칙.
지켜오던것도 있고 원칙은 알고있었지만 이런저런 이유로 현실에는 적용하기 어려운 부분도 있지만 이런 원칙을 상기하면서 개발하면 좀 더 일관성있는 API를 구성할 수 있을듯 하다.

목차만으로도 많은 의미가 전달되기에 여기 발췌해둔다.

02장. URI 식별자 설계
  02 URI 형태
    규칙: 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
    규칙: URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
    규칙: 하이픈(-)은 URI 가독성을 높이는 데 사용한다.
    규칙: 밑줄( _ )은 URI에 사용하지 않는다.
    규칙: URI 경로에는 소문자가 적합하다.
    규칙: 파일 확장자는 URI에 포함시키지 않는다.
  03 URI 권한 설계
    규칙: API에 있어서 서브 도메인은 일관성 있게 사용해야 한다.
    규칙: 클라이언트 개발자 포탈 서브 도메인 이름은 일관성 있게 만들어야 한다.
  04 리소스 모델링
  05 리소스 원형
    도큐먼트.
    컬렉션.
    스토어.
    컨트롤러.
  06 URI 경로 디자인
    규칙: 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
    규칙: 컬렉션 이름으로는 복수 명사를 사용해야 한다.
    규칙: 스토어 이름으로는 복수 명사를 사용해야 한다.
    규칙: 컨트롤러 이름으로는 동사나 동사구를 사용해야 한다.
    규칙: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
    규칙: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.
  07 URI Query 디자인
    규칙: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
    규칙: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 한다.

3장. HTTP를 이용한 인터랙션 설계
  02 요청 메서드
    규칙: GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안 된다.
    규칙: GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다.
    규칙: 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다.
    규칙: PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다.
    규칙: PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.
    규칙: POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다.
    규칙: POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다.
    규칙: DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다.
    규칙: OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 한다.
  03 응답 상태 코드
    규칙: 200("OK")는 일반적인 요청 성공을 나타내는 데 사용해야 한다.
    규칙: 200("OK")는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다.
    규칙: 201("Created")는 성공적으로 리소스를 생성했을 때 사용해야 한다.
    규칙: 202("Accepted")는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다.
    규칙: 204("No Content")는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다.
    규칙: 301("Moved Permanently")는 리소스를 이동시켰을 때 사용한다.
    규칙: 302("Found")는 사용하지 않는다.
    규칙: 303("See Other")은 다른 URI를 참조하라고 알려줄 때 사용한다.
    규칙: 304("Not Modified")는 대역폭을 절약할 때 사용한다.
    규칙: 307("Temporary Redirect")은 클라이언트가 다른 URI로 요청을 다시 보내게 할 때 사용해야 한다.
    규칙: 400("Bad Request")은 일반적인 요청 실패에 사용해야 한다.
    규칙: 401("Unauthorized")은 클라이언트 인증에 문제가 있을 때 사용해야 한다.
    규칙: 403("Forbidden")은 인증 상태에 상관없이 액세스를 금지할 때 사용해야 한다.
    규칙: 404("Not Found")는 요청 URI에 해당하는 리소스가 없을 때 사용해야 한다.
    규칙: 405("Method Not Allowed")는 HTTP 메서드가 지원되지 않을 때 사용해야 한다.
    규칙: 406("Not Acceptable")은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야 한다.
    규칙: 409("Conflict")는 리소스 상태에 위반되는 행위를 했을 때 사용해야 한다.
    규칙: 412("Precondition Failed")는 조건부 연산을 지원할 때 사용한다.
    규칙: 415("Unsupported Media Type")은 요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야 한다.
    규칙: 500("Internal Server Error")는 API가 잘못 작동할 때 사용해야 한다.

4장. 메타데이터 디자인
  01 HTTP 헤더
    규칙: Content-Type을 사용해야 한다.
    규칙: Content-Length를 사용해야 한다.
    규칙: Last-Modified는 응답에 사용해야 한다.
    규칙: ETag는 응답에 사용해야 한다.
    규칙: 스토어는 조건부 PUT 요청을 지원해야 한다.
    규칙: Location은 새로 생성된 리소스의 URI를 나타내는 데 사용해야 한다.
    규칙: Cache-Control, Expires, Date 응답 헤더는 캐시 사용을 권장하는 데 사용해야 한다.
    규칙: Cache-Control, Expires, Pragma 응답 헤더는 캐시 사용을 중지하는 데 사용해야 한다.
    규칙: 캐시 기능은 사용해야 한다.
    규칙: 만기 캐싱 헤더는 200("OK") 응답에 사용해야 한다.
    규칙: 만기 캐싱 헤더는 '3xx' 와 '4xx' 응답에 선택적으로 사용될 수 있다.
    규칙: 커스텀 HTTP 헤더는 HTTP 메서드의 행동을 바꾸는 데 사용해서는 안 된다.
  02 미디어 타입
    미디어 타입 문법
    등록된 미디어 타입
    벤더 고유 미디어 타입
  03 미디어 타입 설계
    규칙: 애플리케이션 고유 미디어 타입을 사용해야 한다.
    규칙: 리소스의 표현이 여러 가지 가능할 경우 미디어 타입 협상을 지원해야 한다.
    규칙: query 변수를 사용한 미디어 타입 선택을 지원할 수 있다.

5장. 표현 디자인
  01 메시지 바디 포맷
    규칙: JSON 리소스 표현을 지원해야 한다.
    규칙: JSON은 문법에 잘 맞아야 한다.
    규칙: XML과 다른 표현 형식은 선택적으로 지원할 수 있다.
    규칙: 추가 봉투는 없어야 한다.
  02 하이퍼미디어 표현
    규칙: 링크는 일관된 형태로 나타내야 한다.
    규칙: 링크 관계를 표현할 때에는 일관된 형태를 사용해야 한다.
    규칙: 링크를 표현할 때는 일관된 형태를 사용해야 한다.
    규칙: 응답 메시지 바디 표현에 셀프 링크를 포함해야 한다.
    규칙: 진입 API URI 수를 최소화하라.
    규칙: 리소스의 상태에 따라 가능한 액션을 표현하기 위해서 링크를 사용해야 한다.
  03 미디어 타입 표현
    규칙: 미디어 타입 format은 일관성 있는 폼을 사용해야 한다.
    규칙: 미디어 타입 스키마를 표현할 때는 일관성 있는 형식을 사용해야 한다.
  04 오류 표현
    규칙: 오류는 일관성 있게 표현한다.
    규칙: 오류 응답은 일관성 있게 표현한다.
    규칙: 일반적인 오류 상황에서는 일관성 있는 오류 타입을 사용해야 한다.

6장. 클라이언트 영역
  02 버전을 정의하는 방법
    규칙: 새로운 개념을 도입하려면 새로운 URI를 사용해야 한다.
    규칙: 표현 형태의 버전을 관리하기 위해서는 스키마를 사용해야 한다.
    규칙: 엔티티 태그는 표현 상태 버전을 관리하기 위해 사용한다.
  03 보안
    규칙: 리소스 보호를 위해 OAuth를 사용할 수 있다.
    규칙: 리소스 보호를 위해 API 관리 솔루션을 사용할 수 있다.
  04 응답 표현 조합
    규칙: URI의 쿼리 부분은 부분 응답을 지원할 때 사용해야 한다.
    규칙: URI 쿼리 부분은 연결된 리소스를 포함할 때 사용해야 한다.
  05 하이퍼미디어 처리
  06 자바스크립트 클라이언트
    규칙: 자바스크립트에서 여러 웹 사이트에 읽기 접근이 가능하도록 JSONP를 지원해야 한다.
    규칙: 자바스크립트에서 여러 웹 사이트에 읽기/쓰기 접근이 가능하도록 CORS를 지원해야 한다.

스트럿츠 2.1.이 릴리즈 되었습니다. 요즘 MS쪽 어플리케이션 개발 프로젝트를 하고있지만 여전히 자바쪽 흐름을 읽는것도 게을리 하고 있지 않습니다만, 쉽지 않네요.

스트럿츠 2.1은 많은 양의 코드를 Plug-In Framework로 옮기는 리펙토링, Convention plug-in에 의한 XML 설정 감소, 향상된 REST 지원에 초첨을 두고 진행되었습니다.

InfoQ에서 스트럿츠2 커미터인 Musachy Barroso씨와 인터뷰한 기사가 올라와서 포스팅 합니다.

2.0과 2.1의 차이점은 무엇인가요?
많은 수의 버그픽스가 있었습니다. 그리고 REST, Convention, Java Template과 같은 플러그인이 추가되었습니다.

많은 기능이 플러그-인 형태로 변경되었습니다. 이렇게 한 이유는 무엇인가요?
스트럿츠 코어에는 진정한 core만을 남기자는 아이디어에서 출발했습니다. 그리고 나머지는 플러그인에 집어 넣는거죠. 이렇게 하면서 코드의 유지보수가 쉬워 졌습니다. 그러면서 Dojo 플러그인 같은 것들은 더 이상 스트럿츠에서 지원하지 않습니다. 이런 변화는 제거된 플러그인을 사용하지 않는 개발자와 작은 footprint를 원하는 개발자 이외의 사람에게 직접적인 장점은 없습니다.
 
Ajax 태그를 depreciate 한 이유는 무엇인가요?
Struts2의 ajax 태그는 Dojo 0.4.x에 기반하고 있습니다. 그것을 Dojo의 최신버전에 맞춰 포팅하는것은 모든 ajax 태그의 코드를 다시 작성해야한 다는것과도 같은 이야기입니다. Dojo의 새로운 버전은 너무 빨리 출시되고 마이너 버전에서도 변경되는 코드의 양이 너무 많습니다. 태그가 Dojo의 모든 기능을 다 포함하고 있지 않기때문에 개발자는 주로 Dojo 라이브러리를 직접 사용하는 경향이 있습니다. 이런 이유들과 ajax 태그 개발 지원자의 부족으로 ajax 태그를 depreciate 했습니다.

어떤 이유로 CodeBehind 플러그인들을 Convention 플러그인으로 바꾸게 되었나요?
Convention은 외부 프로젝트였고 늦게 Struts에 추가되었습니다. Convention은 좀 더 빠른 ClassPath Scanner, 더 나은 Configuration elements, 로깅, 다양한 configuration 옵션, configuation reloading, 더 나은 문서화 등을 지원합니다.

Java Template 플러그인은 무엇인가요?
Java Template은 FreeMarker를 이용하여 java만으로 구현한 'simple theme' 구현체입니다. 이 플러그인의 태그는 재작성이 불가능한 약점이 있는 원래의 그것보다 4~5배 가량 빠르게 동작합니다.

다른 많은 Web Framework가 있는데 우리는 왜 Strtus2를 선택해야 하나요?
스트럿츠2는 아마도 가장 약한 커플링(loosely-coupled)으로 구현된 프레임워크일 겁니다. 많은 기능이 커스터마이징 없이, 혹은 약간의 커스터마이징만으로 사용할 수 있으며, 프레임워크를 익히기가 쉽습니다. 약한 커플링은 스트럿츠의 실체에 대한 지식 없이도 비지니스 로직을 작성 할 수 있도록 해 줍니다. 그러면서도 스트럿츠는 대용량 트래픽을 발생하는 사이트에서 유연한 확장성을 담보하고 있다는 점입니다.

마지막으로 한마디.
스트럿츠 2.1 출시까지 오랜 기간 공을들였습니다. 우리는 스트럿츠 프레임워크의 빌드와 릴리즈 프로세스 개선을 위해 정말 열심히 일하고 있습니다. 앞으로는 좀 더 짧은 주기로 새로운 버전이 릴리즈 되는것을 기대하셔도 좋습니다.

얼마 전부터, 아니 꽤 오래전부터 가지고 있던 의문이다.
디지털 컨텐츠가 가지는 장점이 무었인가?
원본과 똑같은 복사본을 수없이 만들 수 있다는점과 반영구적인 보존이 가능 하다는거 아닌가?
그런데 디지털 건텐츠의 거대 유통소이자 저장소인 웹의 현실은 어떤가?
원본과 똑같은 복사본을 만들 수 있다는 장점은 눈앞에 접하고있는 컨텐츠가 원본인지.. 변경된 사본은 아닌지를
구분 할 수 없는 치명적인 단점을 수반하며 설령 그게 원본이라 하더라도 그건 오늘의 원본 이지 어제의 원본이 아닐 수 있다.
반영구적이라는 컨텐츠의 수명은 컨텐츠의 소유자, 혹은 컨텐츠가 속한 집단의 문화/성향, 유지 비용 등의 이유로  너무나 간단히 사라져 간다.

그럼 현재의 역사를 기록하고 있는 이런 디지탈 컨텐츠를 어떻게 영구히 유지 할 수 있을까?
이런 생각은 비단 나만 가지고 있던게 아니다. 이미 인터넷아카이브 라는 비영리 조직 의해 세계의 웹페이지들이 수집/보관 되고 있다.  관련기사 보기
모르긴 몰라도 이와 유사한 목적으로 활동하는 조직이나  진행되는 프로젝트들이 얼마간은 더 있을것이다.
하지만, 인터넷아카이브의 예를 보더라도 수집되는 웹사이트의 모든 페이지가 기록 되는 건 아니다.

개인이 만들어 내는 수많은 역사의 일부를 어떻게 보관 할 수 있을까?
이런 고민에 대해 기술적이 부분까지 고민을 진행 해 보진 않았지만 어렴풋이나마 '웹 사이트 무덤'과 같은 서비스를 생각 해 본 적이 있다.
- '무덤'이라는 단어의 어감이 좋지만은 않지만 더이상 활동하지 않는 사이트의 컨텐츠를 유지하며 온라인상에
흔적을 남겨 놓는다는 점에서 무덤이라 단어를 사용했을 뿐이다. -
사이트를 소유하고 운영하던 사람이 어떤 이유로 사이트와 그 컨텐츠를 유지할 능력을 상실 할 경우 무덤을 관리하는 단체
- 영리와 비영리는 또다른 문제 - 에 사이트 보관을 의뢰하면 그 단체에서는 영구적으로 그 정보를 보관 해 주는것이 기본적인 얼개이다.
'여전히 유지 비용 문제가 남게 되지만 최소한 온라인 컨텐츠가 일순간 사라지는 건 막을 수 있지 않을까'하는 상상을 하곤 했다.
이건 순전히 개인적인 상상으로, 실현되기 위해서는 수많은 현실적 문제들을 해결 해야 할 것이다.

이런 형태가 아니더라도 어떻게든 온라인 컨텐츠를 다음세대에 전달 할 방법이 필요하다고 생각한다.

인류가 만들어낸 그 어떤 문명의 속도보다 빠르게 변화하는 온라인 세상의 컨텐츠에 어떻게 영속성을 부여할 수 있을까?