2013년 7월 28일

Restful API, URI 이름 설계

Restful API 이름 명명 간단 요약

URI 형태

  • 규칙1: 슬래시(/) 구분자는 계층 관계를 나타내는데 사용한다.
  • 규칙2: URI 마지막 문자로 슬래시를 포함하지 않는다.
  • 규칙3: 하이픈(-)은 URI 가독성을 높이는데 사용한다.
  • 규칙4: 밑줄(_)은 URI 경로에 사용하지 않는다.
  • 규칙5: URI 경로는 소문자가 적합하다.
  • 규칙6: 파일 확장자는 URI에 포함시키지 않는다.


URI 경로디자인

  • 규칙1: 도큐먼트 이름으로는 단수명사를 사용해야한다.
  • 규칙2: 컬렉션 이름으로는 복수명사를 사용해야한다.
  • 규칙3: 스토어 이름으로는 복수명사를 사용해야한다.
  • 규칙4: 컨트롤러 이름으로는 동사나 동사구를 사용해야한다.
  • 규칙5: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
  • 규칙6: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.


URI Query 디자인

  • 규칙1: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
  • 규칙2: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는데 사용해야한다.



HTTP를 이용한 인터렉션 설계 - 요청 메서드

  • 규칙1: GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안된다.
  • 규칙2: GET 메서더는 리소스의 상태 표현을 얻는데 사용해야한다.
  • 규칙3: 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야한다.
  • 규칙4: PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는데 사용해야한다.
  • 규칙5: PUT 메서드는 변경 가능한 리소스를 갱신하는데 사용해야한다.
  • 규칙6: POST 메서드는 컬렉션에 새로운 리소스를 만드는데 사용해야한다.
  • 규칙7: POST 메서드는 컨트롤러를 실행하는데 사용해야한다.
  • 규칙8: DELETE 메서드는 그 부모에서 리소스를 삭제하는데 사용해야한다.
  • 규칙8: OPTIONS 메서드는 리소스의 사용 가능한 인터렉션을 기술한 메타데이터를 가져오는데 사용해야한다.


HTTP를 이용한 인터렉션 설계 - 응답상태코드

  • 규칙1: 200("OK")는 일반적인 요청 성공을 나타내는데 사용해야한다.
  • 규칙2: 200는 응답 바디에 에러를 전송하는데 사용해서는 안된다.
  • 규칙3: 201("created")는 성공적으로 리소스를 생성했을 때 사용해야한다.
  • 규칙4: 202("accepted")는 비동기 처리가 성공적으로 시작되었을음을 알릴 때 사용해야한다.
  • 규칙5: 204("No Content")는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다.
  • 규칙6: 301("Moved Permanently")는 리소스를 이동시켰을 때 사용한다.
  • 규칙7: 302("Found")는 사용하지 않는다.
  • 규칙8: 303("See Other")는 다른 URI를 참조하라고 알려줄 때 사용한다.
  • 규칙9: 304("Not Modified")는 대역폭을 절약할 때 사용한다.
  • 규칙10: 307("Temporary Redirect")은 클라이언트가 다른 URI로 요청을 다시 보내게할 때 사용해야한다.
  • 규칙11: 400("Bad Request")는 일반적인 요청 실패에 사용해야한다.
  • 규칙12: 401("Unauthorized")는 클라이언트 인증에 문제가 있을 때 사용해야한다.
  • 규칙13: 404("Not Found")는 요청 URI에 해당하는 리소스가 없을 때 사용해야한다.
  • 규칙14: 405("Method Not Allowed")는 HTTP 메서드가 지원되지 않을 때 사용해야한다.
  • 규칙15: 406("Not Acceptable")는 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야한다. 
  • 규칙16: 409("Conflict")는 리소스 상태에 위반되는 행위를 했을 때 사용해야한다.
  • 규칙17: 412("Unsupported Media Type")는 요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야한다.
  • 규칙18: 500("Internal Server Error")는 API가 잘못 작동할 때 사용해야한다.


메타데이터 디자인 - HTTP 헤더

  • 규칙1: Content-Type, Content-Length, Last-Modified, ETag는 응답에 사용해야한다.
  • 규칙2: 스토어는 조건부 PUT 요청을 지원해야한다.
  • 규칙3: Location는 새로 생성된 리소스의 URI를 나타내는데 사용해야한다.
  • 규칙4: Cache-Control, Expires, Date 응답헤더는 캐쉬 사용을 권장하는데 사용해야한다.
  • 규칙5: Cache-Control, Expires, Pragma 응답 헤더는 캐쉬 사용을 중지하는데 사용해야한다.
  • 규칙6: 캐쉬 기능을 사용해야한다.
  • 규칙7: 만기 캐슁 헤더는 200("OK") 응답에 사용해야한다.
  • 규칙8: 만기 캐슁 헤더는 '3XX', '4XX' 응답에 선택적으로 사용될 수 있다.
  • 규칙9: 커스텀 헤더는 HTTP 메서드의 행동을 바꾸는데 사용해서는 안된다.


메타데이터 디자인 - 미디어 타입 설계

  • 규칙1: 어플리케이션 고유 미디어 타입을 사용해야한다.
  • 규칙2: 리소스의 표현이 여러가지 가능할 경우 미디어 타입 협상을 지원해야한다.
  • 규칙3: query 변수를 사용한 미디어 타입 선택을 지원할 수 있다.


원문 출처:
REST API Design Rulebook
Designing Consistent RESTful Web Service Interfaces
Publisher: O'Reilly Media
Released: October 2011

번역 출처: 권원상님, 김관래님 번역



2013년 7월 27일

curl를 이용한 http client, smtp client.


curl은 서버로부터 데이터를 가져올 수 있는 도구이다. curl은 libcurl(3)를 기반으로 한다.
(libcurl - client-side URL transfer)
crul homepage: http://curl.haxx.se/

curl  is  a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user inter-action.

curl offers a busload of useful tricks like proxy support, user authen-tication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume and more. As you will see below, the number of features will make your head spin!

curl is powered by  libcurl  for all transfer-related features. See libcurl(3) for details.

1. http client로 사용하기

응답 데이터 출력

간단하게 URL를 입력하면 응답 데이터를 화면에 보여준다.

$ curl http://curl.haxx.se

응답 데이터를 파일로 저장하기(-o FILENAME)

curl-refined.jpg 파일을 image.jpg 파일로 저장한다.

$ curl http://curl.haxx.se/pix/curl-refined.jpg -o image.jpg

"-#" 옵션을 추가하면 얼마나 다운로드 되고 있는지 화면상에 출력해준다.


$ curl http://curl.haxx.se/pix/curl-refined.jpg -o image.jpg -#
######################################################################## 100.0%

클라이언트의 요청 및 응답데이터를 모두 출력(저장)하기

--trace FILENAME: 옵션을 사용하면 요청 및 응답시 헤더 및 바디 내용을 지정한 파일에 모두 저장한다.
--trace-ascii FILENAME: --trace 보다 조금 더 읽기 쉽다.
--trace-time: 요청 및 응답에 대한 시간 정보를 출력한다.

"FILENAME" 대신에 간단히 '-'만 입력하면 출력내용을 모두 화면에 보여준다.

$ curl  --trace-ascii - --trace-time http://naver.com

14:17:54.485591 == Info: About to connect() to naver.com port 80 (#0)

14:17:54.485745 == Info:   Trying 202.131.30.11...

14:17:54.501270 == Info: connected

14:17:54.501320 == Info: Connected to naver.com (202.131.30.11) port 80 (#0)

14:17:54.501377 => Send header, 140 bytes (0x8c)

0000: GET / HTTP/1.1

0010: User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0

0050:  OpenSSL/0.9.8x zlib/1.2.5

006c: Host: naver.com

007d: Accept: */*

008a:

14:17:54.507130 <= Recv header, 32 bytes (0x20)

0000: HTTP/1.1 301 Moved Permanently

14:17:54.507204 <= Recv header, 15 bytes (0xf)

0000: Server: nginx

14:17:54.507215 <= Recv header, 37 bytes (0x25)

0000: Date: Sun, 28 Jul 2013 05:17:54 GMT

14:17:54.507231 <= Recv header, 25 bytes (0x19)

0000: Content-Type: text/html

14:17:54.507243 <= Recv header, 21 bytes (0x15)

0000: Content-Length: 178

14:17:54.507255 <= Recv header, 24 bytes (0x18)

0000: Connection: keep-alive

14:17:54.507267 <= Recv header, 33 bytes (0x21)

0000: Location: http://www.naver.com/

14:17:54.507279 <= Recv header, 34 bytes (0x22)

0000: Vary: Accept-Encoding,User-Agent

14:17:54.507292 <= Recv header, 2 bytes (0x2)

0000:

14:17:54.507301 <= Recv data, 178 bytes (0xb2)

0000: 

0008: 301 Moved Permanently

003b: 

0053: 

301 Moved Permanently

0084:
nginx
00a0: 00a9: 301 Moved Permanently

301 Moved Permanently


nginx
14:17:54.507361 == Info: Connection #0 to host naver.com left intact 14:17:54.507381 == Info: Closing connection #0