안녕하세요, 생각의 웹입니다.


오늘은 REST API에 대해 검색하다가 우연히 발견한 좋은 포스팅이 있어 기록 겸해서 이렇게 링크를 공유합니다.


1. 개념 소개

2. API 설계 가이드

3. API 보안


방대한 내용을 이렇게 잘 정리해 주셔서 덕분에 더 많은 것을 배웠습니다.

특히 API 보안에 관한 부분은 기존 Web Service 1.0 (SOAP)에 비해 취약하다는 논란이 있어서 좀 더 공부해 봐야 겠다는 찰나에 좋은 글을 만나게 되었습니다.


열린 마음으로 좋은 내용들을 공유해 주시는 고수님들을 본받아 저도 열심히 수련하고 잘 나눠야 겠다는 마음을 품습니다.

 

감사합니다.

행복한 하루 되시길!

안녕하세요. "생각의 웹"입니다.


지난 포스트에서 말씀드린 바와 같이 이번 글에서는 객체에 의미를 부여하기 위해 객체 정의 이후 객체의 속성과 메소드를 추가하는 법에 대해 설명드리려고 하는데, 이에 앞서 지난 번에 생략하고 지나간 Web IDL에서 제공하는 형(type)들에 대해 먼저 언급하고자 합니다.


1. Web IDL 의 기본 형들 (types)

이런 글을 읽는 분이라면 이 형이 동네에서 노는 형들을 의미하는 것이 아닌 것은 아시리라 믿지만 왕초보자를 위해 프로그래밍 언어의 가장 기초적인 내용을 말씀드리죠. 


컴퓨터는 0 과 1 외에는 알지 못하지만 수 많은 0과 1을 (2진수라고 합니다.) 엄청나게 빠른 시간 내에 처리할 수 있는 능력을 지녔습니다. 하지만 컴퓨터에게 일을 시키는 역할을 하는 프로그램을 짜는 건 사람이다 보니 2진수보다 10진수로 표기되는 정수(integer)와 실수(float point number) 그리고 문자열(string) 등에 익숙합니다. 따라서 대부분의 프로그래밍 언어는 이런 형들을 지정해주면 컴퓨터가 이해할 수 있는 2진수로 변환해 주는 기능을 합니다. 더욱이 자바스크립트 언어는 타입이 없는 (untyped language) 언어라고 불리는 데 특별히 형을 지정해 주지 않아도 값을 통해 형을 유추하는 기능을 제공한다는 의미로 보면 됩니다.


뻔한 이야기를 다시 하는 이유는 자바스크립트에서는 형을 지정해 줄 필요가 없더라도 API 입장에서 보면 상황이 다릅니다. API를 사용하고자 하는 프로그래머에게 호출하고자 하는 대상에 전달할 값의 형을 알려주어야 하기 때문입니다. 자바스크립트에서는 필요에 따라 암묵적으로 형 변환 (implicit type conversion)이 일어나지만 종종 의도치 않는 변환이 일어날 수 있기에 주의해야 합니다.


다시 기본 제공하는 형들 (primitive types)의 예약어들(reserved keywords)를 보편적으로 많이 쓰는 C/C++/Java를 기준으로 나열해 보면,


  • 참/거짓 형: bool
  • 정수 형: { signed | unsigned } short, int, long
  • 실수 형: { signed | unsigned } float, double
  • 문자 형: char, char[], char*, String
정수 형이나 실수 형은 +/- 부호 유무와 숫자를 담을 수 있는 크기 (16 bytes, 32 bytes, 64 bytes)에 따라, 문자 형은 문자의 인코딩(encoding) 방식과 문자열의 길이 등에 따라 각기 다른 형을 지정해 주고 사용해야 합니다.

Web IDL에서는 이와 유사하게 다음과 같은 예약어들을 사용합니다.

  • 참/거짓 형: boolean
  • 정수 형: byte, {unsigned} short, long
  • 실수 형: {unsigned} float, double
  • 문자 형: DOMString
  • 객체 형: object  

이외에 임의의 형 (any) 등도 있으니 자세한 사항은 Web IDL spec.를 확인하시기 바라며, int 가 예약어가 아니라는 점 유의하시면 좋을 것 같습니다.

2. 속성 정의하기

형들에 대해 이해하셨다면 이런 형들을 가진 속성들(attributes)을 객체에 추가해 보기로 하죠. 지난 글에서 작성했던 Web IDL 설계를 다시 기재하겠습니다.

[Constructor]

[Constructor(DOMString model)]

interface ArduinoBoard {


};


이제 생성자에서 받은 model이라는 parameter를 속성으로 객체에 저장하기 위해 model attribute를 추가해 봅시다.


속성을 설계하는 문법은 다음과 같습니다.


interface 인터페이스_이름 {

attribute 속성의_형 속성의_이름;

};



[Constructor]

[Constructor(DOMString model)]

interface ArduinoBoard {


attribute DOMString modelName;

};

간단하죠? 이로써 멍텅구리 객체가 정보를 갖는 객체로 진화했습니다. ;-)



3. 메소드 정의하기


객체가 속성만을 지니고 있다면 소극적인 느낌이죠. 이번에는 객체에 행위를 부여하기 위해 메소드를 추가해 봅니다.


메소드는 메소드 이름, 메소드의 인자들(parameters), 메소드의 반환 형 (return type)으로 구성되어 있고 문법은 다음과 같습니다.


interface 인터페이스_이름 {

    반환_형 메소드_이름(인자_형 인자_이름, ...);

};


유념할 사항 중 하나는 설계 시, 메소드 오버로딩(method overloading) 기법을 사용하게 되면 의도치 않은 오류를 일으킬 수 있다는 점인데, 이는 자바스크립트에서는 자동 형 변환이 일어나기 때문입니다. 


백문불여일견이니 예시로 문자열을 전송하는 쓰기 메소드를 설계해 보죠.


[Constructor]

[Constructor(DOMString model)]

interface ArduinoBoard {


attribute DOMString modelName;

void write(DOMString msg);

};

이 메소드는 메세지를 쓰고 결과를 반환하지 않도록 (void) 설계했습니다. 


지금까지 객체에 속성과 메소드를 정의하는 법을 설명드렸습니다. 여기까지 설명드린 것으로도 간단한 자바스크립트 API를 설계하실 수 있게 되었습니다. 축하드립니다!


하지만, 자바스크립트는 생각하는 것보다 만만치 않은 언어입니다. 조금 더 공부해 보시면 아마 곧 깨닫게 되실 겁니다. 따라서 다음 포스팅은 자바스크립트 언어의 특징을 살려서 API를 보다 상세히 설명하는 내용으로 준비해 보려고 합니다.


긴 글 읽어주셔서 감사드리며 궁금한 점 댓글로 남겨주시면 성실히 답변드리도록 하겠습니다. 행복한 하루 되시길!!!

 

"생각의 웹" 입니다.


지난 두번의 포스팅에서 이 글을 쓰는 배경관련 도구에 대해 설명드렸습니다.


이 글부터는 본격적으로 JavaScript API를 Web IDL로 설계하는 방법을 duino 라는 Arduino 제어를 위한 JavaScript API를 예제로 해서 Web IDL 기본 문법부터 차근 차근 알려드리도록 하겠습니다.


먼저, duino의 샘플 코드를 다시 보죠.


var arduino = require('duino'),
    board = new arduino.Board({
     device: 'USB0'
});

var led = new arduino.Led({
  board: board,
  pin: 13
});

led.blink();

소스 코드에 대해 간단히 설명드리면 arduino 변수에 'duino' 모듈을 불러와 Board 초기화를 수행하는 Board 객체를 board 변수로 생성하게 됩니다. 이후 Led 점멸을 위해 board 변수를 초기 입력 값으로 받는 Led 객체를 생성해 led 변수로 저장후 blink() 함수를 통해 점멸 기능을 손쉽게 수행하게 됩니다. 


먼저, require() 함수는 Node.JS에서 자바 스크립트 모듈화를 위해 제공하는 함수로 아직 자바스크립트 표준 (ECMAScript 5)으로 제공되지 않기에 Web IDL에서도 표현할 수 없기에 따라서 모듈화 함수 및 모듈화 함수를 통해 가져온 변수를 마치 namespace로 사용하는 부분(new arduino.Board(...) )은 제약사항으로 두고 생성자 함수인 new 키워드를 이용해 설계하는 부분부터 시작하겠습니다.

1. 객체를 정의하기

가장 널리 알려진 객체 지향 언어인 C++, Java 등에서는 객체를 찍어내는 틀을 클래스(class)라고 합니다만 Web IDL에서는 인터페이스(interface)라는 키워드를 사용합니다. (인터페이스는 C++, Java에서는 다른 의미로 사용하는 키워드이기에 혼동하면 안됩니다. )


인터페이스를 설계할 때의 기본 문법은 다음과 같습니다.


interface 인터페이스_이름 {


};


여기서 인터페이스_이름에 알맞은 인터페이스 이름을 지정하면 됩니다. 이 이름은 보통 공백을 포함하지 않는 영 단어 혹은 영 단어의 조합을 의미하며 단어의 시작은 대문자로 시작하고 그 외는 소문자로 작성하는 것을 권고합니다.


예를 들면 올바른 인터페이스의 이름으로 Board, ArduinoBoard, Led, LedLamp 와 같이 명명할 수 있습니다.

  

2. 객체를 생성하기

기존 객체 지향 언어들과 다르게 Web IDL에서 정의한 인터페이스에 대한 객체를 생성하기 위해서는 [Constructor] 확장 속성을 지정해 주어야 합니다. 이 확장 속성은 생성자 함수가 가지는 인자(parameter)들에 대해 설명해 줄 수 있습니다.

앞서 정의한 인터페이스에 별다른 인자가 없이 생성 가능한 객체를 정의하려면 다음과 같이 설계하면 됩니다.


[Constructor]

interface 인터페이스_이름 {


};

상기와 같이 설계할 경우, 객체를 다음과 같이 생성할 수 있게 됩니다.


var myObj = new 인터페이스_이름();


생성자 함수에 인자가 필요할 경우, 다음과 같이 설계합니다.

[Constructor(인자의_형식 인자_이름)]
[Constructor(인자의_형식 인자_이름, 인자의_형식 인자_이름)] 


인자의_형식은 또다른 인터페이스의_이름이거나 추후 설명할 ECMAScript의 기본 형식 등이 될 수 있으며, 인자_이름은 소문자로 시작하는 영 단어나 복합 단어입니다. (복합 단어일 경우, 두번째 단어부터는 공백없이 대문자로 시작하는 단어로 표기하는데 이걸 낙타 모양을 닮았다고 해서 보통 camel case 라고 부릅니다.)


마지막으로 [Constructor] 확장 속성은 여타 객체 지향 언어의 생성자 함수처럼 여러 번 지정이 가능합니다. 예를 들면, 


[Constructor]

[Constructor(DOMString model)]

interface ArduinoBoard {


};

위와 같이 설계할 경우, 다음과 같이 두 가지 형태로 객체를 생성할 수 있습니다.

var board1 = new ArduinoBoard();
var board2 = new ArduinoBoard("ArduinoNano");


지금까지 객체를 정의하고 생성하는 법에 대해 설명드렸습니다. 아직 객체에 아무런 정보가 없기에 생성한 객체로는 아무 일도 할 수 없습니다. 다음 글에서는 이 객체에 속성(attribute)와 메소드 (method)를 정의하는 법을 설명드리도록 하겠습니다.


알고 있는 지식을 꾸준하게 글로 적어 가는 습관이 잘 들지 않아 관심가지고 계속 구독해 주시는 분들께 죄송할 따름입니다. ^^;


늘 행복하시고 해피 코딩하시기 바랍니다.


"생각의 웹"입니다.


 "Web IDL로 JavaScript API를 설계하기" 시리즈의 첫 번째 포스팅에서 이 작업의 당위성에 대해 말씀드렸으니 이제는 도구를 설치하고 사용해 보기로 합시다.


지난 번 포스팅에서 소개해 드린 widlproc 도구는 Web IDL로 작성된 설계 문서를 XML 형태로 변환할 뿐만 아니라 연계된 도구를 통해 해당 xml에 대한 dtd와 xslt 문서를 통해 html 문서를 생성해 줍니다. 다시 말씀드리면, Web IDL로 설계한 사항에 대한 문법 적합성(문법 오류 및 완결성 등)를 검증(validation) 해서 이상이 있을 경우 해당 위치를 알려주고 문제가 없을 시 XML 문서로 내뱉어 줍니다. 이 XML를 이용해 사람이 읽을 수 있는 HTML 문서를 생성할 수 있으며 또한 이 정보를 기반으로 해당 API에 대한 코드 템플릿(stub code)을 생성하여 개발 생산성을 향상시킬 수 있습니다.


그럼 도구를 받아 설치해 보도록 합시다.

   

  1. 먼저 아래 github에서 widlproc를 다운로드 받습니다. 
    (https://github.com/dontcallmedom/widlproc)
    git clone 하거나 해당 페이지에서 다운로드 받을 수 있습니다.

  2.  해당 페이지에는 마치 windows에서 동작하는 것처럼 가이드되어 있으나 리눅스를 사용하시길 권장합니다. 윈도우즈 상에서 cygwin을 까느니 virtualbox 기반 ubuntu를 사용하는게 속 편하실 겁니다. XML 관련 도구들이 대부분 리눅스에서 제공되는 것들이기 때문입니다. 저는 아래와 같이 virtualbox에 ubuntu 14.04 LTS를 설치하여 작업했습니다.



  3. 다운로드 받은 파일이 존재하는 경로에서 Makefile 을 확인한 뒤 make 명령을 수행합니다. 빌드를 위해 필요한 라이브러리가 있다는 메세지가 나오는 경우, apt-get install 명령을 통해 설치하도록 합니다.

  4. 빌드가 정상적으로 완료되면 해당 경로 아래 obj 폴더가 생성되고 이 경로에 widlproc 이라는 실행 파일이 존재하게 됩니다.

  5. 도구의 사용법과 Web IDL 문법 및 documentation rule에 대한 정보는  /doc/widlproc.html 파일을 참고하시기 바랍니다.

  6. 간단한 테스트를 위해 함께 제공하고 있는 샘플 Web IDL 문서를 가지고 widlproc 도구를 실행해 봅시다. /examples 경로에 가면 *.widl 문서가 있습니다. 미리 알려드릴 사항은 이 문서들은 현재 widlproc 도구에서 더 이상 허용하지 않는 Web IDL 문법을 포함하고 있다는 점입니다. 따라서, 수행 결과 문법 에러 화면을 보시더라도 크게 놀라지 않으시기 바랍니다. (저는 놀랐거든요;;)

  7. *.widl 문서를 바로 *.html 문서로 생성해 주는 Makefile이 /examples 경로에 있습니다. 해당 파일을 열어 경로가 제대로 되었는지 확인합니다.



  8. make 명령을 수행하여 widl 문서를 html 문서로 변환합니다. 필요한 모든 도구가 설치되어 있다면  module ... { 으로 시작하는 라인에서 오류가 있다고 알려줍니다. (혹시 도구가 필요하다고 나오면 해당 도구를 apt-get install {도구 명} 명령으로 설치합니다. ) 여기까지 하시면 모든 작업을 제대로 수행하신 겁니다.


여기서 발생하는 오류들은 예제로 제공되고 있는 bondi.widl, filesystem.widl를 작성한 시점 이후에 Web IDL 문법은 많은 개정이 있었기 때문에 이에 맞춰 widlproc 코드는 업데이트 된 반면 예제 코드는 업데이트 되지 않아 발생한 문제입니다. 


따라서, 다음 포스팅은 지난 arduino JavaScript API 관련 포스팅에서 간략히 정리했던 Web IDL로 HTML 문서를 생성한 사례을 들어 Web IDL로 설계하는 법을 소개하도록 하겠습니다.


오늘 포스팅은 여기까지 입니다.


관심 가져주셔서 감사합니다.

늘 행복한 하루 되시길...    



  


+ Recent posts