Tutorial 1: Application ID 등록 하기

2015년 10월 05일 by 청기와랩

청기와랩 SMS Open API 를 사용하기 위한 튜토리얼 입니다.

청기와랩의 SMS API를 사용하는 방법은 매우 간단합니다.

1. 사이트 가입
2. Application ID 등록 (API Key 발급)
3. GitHub 에서 예제 다운로드
4. SMS 응용 프로그램 (또는 웹사이트) 개발
5. Credit 결제

자 그럼 차근 차근 알아 볼까요?

일단 가장 먼저 청기와랩 사이트에 가입 하세요. 우측 상단의 Login 버튼을 클릭하면 나오는 로그인 다이얼로그에서 서비스 가입 링크를 발견 하실 수 있습니다. 

간단히 Email 과 비밀번호, 이름, 전화번호를 입력하고 이용약관에 동의하시면 가입 완료!

이제 SMS 발송을 위한 API Key를 발급받을 차례입니다.

sms   smsapi   tutorial  

---

API 인증

2014년 10월 10일 by 청기와랩

(지난편 Simple! Simple! Simple!에 이어서...)
그럼 청기와랩의 SMS 오픈API에서 인증은 어떻게 할까요?

그냥 HTTP Basic Auth (RFC 2617) 을 사용 합니다.

간단하죠?

뭔가 어려워 보이지만 사실 간단한 겁니다.
사내 인트라넷 쓰다가 특정 페이지에 접근 하면 아래 스크린샷 처럼 웹브라우져에서 인증 다이얼로그 뜨는거 있죠?  이런거...

HTTP 표준에 의거하여 웹서버가 Status 401 을 리턴하면 브라우져가 띄우는 창인데요. 이게 HTTP Basic Auth 입니다.
지금 보신 스크린샷은 사실 청기와랩의 Open API에서 사용하는 URI 를 사파리 브라우져에 갖다 붙이면 볼수 있는 것입니다. 보시는 바와 같이 인증창이 뜹니다. 여러분이 등록하신 App ID와 그것의 API Key를 입력하시면 JSON 데이타를 웹 브라우져 로도 확인 하실 수 있습니다.

https://api.bluehouselab.com/smscenter/v1.0/result/발송ID 를 브라우져에 입력해서 확인 해 보세요. GET Method를 사용하는 청기와랩 SMS API의 다른 URI들도 이렇게 테스트 가능 합니다.

그냥 웹브라우져로도 테스트 가능한 API라니...  표준을 잘 따르고 있는것 맞죠? :-)

또 청기와랩의 RESTful API는 HTTPS (TLS) 를 이용하여 항상 암호화 되어 전송 되므로, 혹시 모를 네트워크 스푸핑 공격으로 부터 API Key를 도난 당할 염려가 없습니다. (단HTTPS 연결 초기화 과정에서 api.bluehouselab.com 이 CA 가 서명한 인증서를 사용하고 있는지 꼭 Verify 과정을 거치도록 해야 더 안전 합니다. 공사 현장이나 네트워크 접속 현장에서는 항상 안전이 우선입니다. ^^)



자 이렇게 웹표준이다 보니 HTTP Basic Auth를 지원하지 않는 HTTP Client 라이브러리는 없겠죠?

고객 여러분들이 사용하는 거의 대부분의 언어와 그 언어에서 사용할수 있는 표준 라이브러리에 포함되어 있는 HTTP 모듈은 모두 포함하고 있는 기능 입니다.

따라서 웹 표준을 잘 따르고 있는 청기와랩의 SMS API는 어떠한 프로그래밍 랭귀지를 사용하던 지, 어떠한 플랫폼/프레임워크를 사용하던지 간에 API 인증부구현을 위해 커스텀한 HTTP Client 구현이 필요 없이 표준으로 제공되는 기능들 만으로 쉽게 적용 가능 합니다.. (그냥 웹브라우져로도 사용 가능한데 뭐 이정도야~ =3)
이것이 청기와랩의 SMS API의 최대 특장점 입니다.

가령 C#의 경우도 .NET에 기본으로 제공 하는  NetworkCredential 클래스를 사용하여 App ID와 Key를 인증에 적용하실 수 있습니다.

Qt5로 작성된 C++ 예제의 경우  QNetworkAccessManager의 시그널 authenticationRequired 에 슬롯을 등록하셔서 적용 하실수 있습니다.

기타... C, Java, Node.js, Python, PHP, Ruby 예제 에서는 어떻게 HTTP Basic Auth를 적용 하고 있는지 지금 바로 청기와랩 GitHub 페이지에서 확인해 보세요~!

https://github.com/BlueHouseLab/sms-openapi


May the code be with you !

sms   openapi   security  

---

한글, EUC-KR vs UTF-8

2014년 10월 01일 by 청기와랩

조만간 돌아오는 한글날 공휴일에 대비하여...
(대왕님 항상 고맙게 생각 합니다... 충성!)

SMS API 를 사용할 때 가장 고민되는 부분이기도 하거니와 한글날의 의미도 되새긴다는 의미에서 오늘은 EUC-KR vs UTF-8 이라는 주제로 기술 블로그를 장식해 볼까 합니다.


EUC-KR, UTF-8은 한글 문자세트의 인코딩 방식 입니다.
한글 문자 세트는 EUC-KR, CP949, UTF-8, UTF-16 등으로 표현될 수 있습니다. 이것을 바로 인코딩이라고 합니다.
한글 문자 세트도 한국 IT 역사에 있어 여러 발전의 과정을 거듭하였는데요.
보통 KSC5601과 Unicode 정도만 기억 하시면 됩니다. (조합형 한글 등의 흑역사를 아신다면 당신은 최소 16진수로 스무살 이상^^)

KSC5601은 완성형 문자세트로 Unix 계열에서는 EUC-KR 인코딩으로 사용 되었고, MS사의 공헌(?)으로 확장 완성형으로 발전 되며 Windows 계열의 OS 에서는 CP949 라는 인코딩으로 널리 사용 되었습니다.
EUC-KR과 CP949는 거의 같다고 보면 됩니다만 EUC-KR이 표현하지 못하는 문자세트를 더 포함하고 있습니다.

가령 "쀍" 같은 글자 말이죠. :-)

잠시 SMS 관련 내용으로 빠지자면...
과거 한국의 CDMA 무선 통신망은 EUC-KR을 사용하여 단문전송 서비스를 지원 하고 있습니다. 아무래도 통신망과 연동되는 네트워크 장비류들은 전통의 Unix 계열에서 돌아갔었기 EUC-KR 이 선택된게  아닐까 추측 되는데, CDMA 쪽 표준의 경우 한국어는 반드시 EUC-KR을 쓰게끔 표준에 명시 되어 있는 부분이 있어 CDMA에 한국 쪽 입김이 꽤 강했었구나 하는 생각도 듭니다.

반면 유럽쪽의 GSM의 단문 전송 표준의 경우 Latin 언어들은 7비트 ASCII 를 사용하는 등, 한 바이트에 한 글자라도 더 보내고자 했던 처절한 몸부림의 흔적이 남아 있는 반면, 한,중,일 등의 언어들은 대충 고민 하고 UCS2 (UTF-16) 을 쓰도록 한 수퍼 쿨한 모습도 보였었죠. 

다시 본론으로 돌아와서...

이후 확장완성형에서 표현하지 못하는 한글은 사용되지 않다 보면 없어질 수도 있다는 위기감과 인터넷의 발달로... 유니코드가 드디어 한글 컴퓨팅 환경의 기본의 자리를 차지하게 되었는데요. Linux 를 필두로한 Unix 기반 OS 들은 EUC-KR 에서 UTF8 또는 UCS4등으로 한국어 Locale 지원을 변경하게 됩니다. 그렇게 대혼란의 몇년이 지나고 지금은 별 불편 없이 UTF-8로 대동단결 하는걸로 정리 되었습니다.
(물론 BSD계열에서 UCS4를 사용하는 것도 있고, UTF-8의 경우 Unicode Normalization 관련하여 타 OS와는 다른 정책 - NFC vs NFD - 을 택하고 있어 여전히 혼란은 조금 남아 있습니다. 특히 Mac OS X에서 가져온 한글 파일명이 다른 OS에서는 분해되는...."한글" <-> "ᄒ ᅡ ᆫ ᄀ ᅳ ᆯ" 그래도 UTF-8 <-> EUC-KR 시 글자가 사라지는 것보다는 훨씬 낫습니다.)

그렇다면... 청기와랩의 SMS API는 무슨 문자세트와 인코딩을 사용하느냐????

바로 바로 유니코드기반의 UTF-8을 기본으로 하고 있습니다.

인터넷에 기반한 Open API 이고 그에 걸맞게 JSON 을 자료 전송 규격으로 채택했기 때문인데요. ECMA-404 표준에 따라 JSON 표기시 Unicode 인코딩 (uHHHH) 또는 UTF-8인코딩으로 문자열을 처리하는 것이 기본 원칙 입니다
("한글"은 UCS2의 uHHHH 포맷으로 "\ud55c\uae00"로 표현 되거나, UTF-8로 그냥 "한글" (ed 95 9c ea b8 80) 표현 됩니다.)

참고로 uHHHH 포멧은 인코딩이 아니라 JSON Data Serialization을 위한 Javascript의 문자열 ESCAPE 처리 규칙입니다.
대다수의 JSON 라이브러리들이 알아서 잘 변환 해주니 걱정하실 필요 없습니다. JSON 라이브러리를 사용할 수 없는 부득이한 상황이라면 그냥 UTF-8로 한글을 사용하시면 됩니다. 이때 HTTP Request 헤더의 Content-Type을  application/json;charset=utf-8 로 설정하면 더 명백 합니다. GitHub 의 청기와랩 SMS API 예제들을 참조하세요.

만약 EUC-KR, CP949, Shift-JS 같은 비 유니코드 문자열 인코딩이 포함되어 있다면 ECMA-404 표준에 의거 JSON 오브젝트로 변환하는 Parsing 과정에서 에러가 발생 됩니다. (청기와랩 SMS API사용시 Status Code 406 Not Acceptable 을 받게 되는 원인 중 하나)

사실 JSON에서의 Unicode 문자열 표현과 관련한 내용은 더 적어야 할게 많지만 그것은 libjson 이나 json.jar같은 각 프로그램 언어별 JSON Library들의 몫으로 남겨두겠습니다. 청기와랩 SMS API 에 고려 되어 있는 EUC-KR 변환 문제 관련 내용은 다음 링크의 주석 부분 참조하세요. http://bluehouselab-sms-openapi.readthedocs.org/ko...


그런데 여전히 시대의 흐름과는 다르게 한글 문제에 있어 여전히 대동단결 하지 못한 OS가 있습니다. 바로 MS WIndows 인데요. 시스템 기본 한글 인코딩으로 CP949 를 사용하므로 인터넷과 관련한 프로그램... 특히 웹브라우져 개발자들이 많은 눈물을 흘렸었죠. 

그런 이유로 Windows 플랫폼에서 여타 OpenAPI를 연동/활용한 개발의 경우, JSON 포맷으로 EUC-KR이나 CP949로 한글을 넣어서 전송한다 던지 하는 실수가 나올 수 있습니다. HTTP Request Header 에 Content-Type에 EUC-KR이나 CP949를 명시하여 극복 할 수도 있습니다만, 그럴 경우 원래 JSON이 아니기도 하거니와, 윈도 환경의 개발자의 경우 EUC-KR 인지 아닌지 모르고 개발 하게 되는 경우가 많아서 인코딩과 관련한 문제가 생겼을때 상당한 시간을 소비하게 되는 경우가 많습니다. 

(청기와랩의 SMS API 예제 코드들은 모두 UTF-8로 작성 되어 있습니다. Windows 환경에서는 GitHub에서 보여주는 코드를 Copy&Paste 할 경우 CP949로 저장될 수 있으므로 꼭 git 로 다운받거나 zip archive로 다운 받아서 실행하세요.)

만약 HTTP Status Code로 406 Not Acceptable을 리턴 받았을 경우 POST로 넘기는 JSON 데이타가 파싱 가능한지와 한글 인코딩이 CP949가 아닌지 먼저 확인해 보시고, Content-Type 부분도 위에 언급한 것 처럼 명백히 지정 되었는지 확인해 보세요.

May the Uni-code be with you...

sms   openapi  

---

Simple ! Simple ! Simple !

2014년 09월 29일 by 청기와랩

Simple is Best.

그런데 청기와랩의 SMS API는 이런 저런 사연이 없습니다.  그냥 표준 !!! 

• 통신프로토콜: HTTP
• 메시징포멧: JSON

다른 여타 OpenAPI들 보면 무슨 사연인지는 모르겠지만 X- 로 시작하는 Prefix 가 들어가는 확장 헤더를 쓴다거나 기타 Custom header 를 추가해야 하는 경우를 볼 수 있는데요. 그렇게 하면 아무래도 HTTP Client 구현이 까다롭고 자연스럽지 않을 수 밖에 없잖아요? 청기와랩의 SMS API는 그런거 없습니다. :-)



또 가장 궁금해 하실 만한 부분은 아무래도 보안 일텐데요. 이것도 그냥 표준 !!!

• 전송 보안은 TLS 1.x (HTTPS) 
• API 인증은 RFC2617 (HTTP Basic Auth)

더 이상의 설명은 필요 없을듯 하죠? 
모두 웹 표준이고, 이것만으로 충분히 안전한 API 사용이 가능합니다.

단, 보안은 아무리 강조해도 지나치지 않다는것... 아시죠?
청기와랩의 API 서버가 아무리 표준 스펙의 보안 모델을 제공한다고 한들, SMS API를 이용하여 Client 를 구현할때 최소한의 안전 수칙도 지키고 있지 않은 채 구현되고 있다면... 보안 위험도가 증가할 수 있습니다.  
안전 수칙은 정말 간단합니다. HTTPS 연결시 Certificate Verification 의 과정을 꼭 잊지 마세요!



마지막으로 API 디자인...
HTTP POST, GET, PUT, DELETE 과 같은 메소드로 정해진 URI 에 접근하는 방식으로 RESTful 한 디자인으로 작성 되어 있습니다.
군더더기 없이 Simple 하고 사용하기도 매우 쉽죠.

어때요? 청기와랩의 SMS API

심플하고 표준에 입각한 진정한 RESTful API 라는게 팍팍 느껴지시나요?


자! 바로 시작해 보세요.

API 문서는 http://bluehouselab-sms-openapi.readthedocs.org/ 에서..
예제 코드는 https://github.com/BlueHouseLab/sms-openapi

그런데 수퍼 개발자 시라면...
그런거 안봐도 바로 터미널 열고

$ git clone https://github.com/BlueHouseLab/sms-openapi.git

May the code be with you...

sms   openapi   HTTP   TLS  

---

Open! Open! Open!

2014년 09월 24일 by 청기와랩

청기와랩의 SMS OpenAPI가 왜 OpenAPI 일까요?

• ReadTheDocs에 공개된 RESTful API 문서
• GitHub에 공개된 다양한 예제 코드

"That's It !"

네, 이게 다 입니다. ^^

고작 10초도 안되는 애플페이 시연 동영상 보여주고 This is Cool ! This is Cool ! 하면서 대중을 설득 해야 하는 팀 쿡의 심정을 누가 이해 해주겠습니까만은...

사실 이거면 다 설명 된겁니다. ^^

Read The Docs 에 공개된 청기와랩 SMS API 문서 입니다. HTTP에 충실한 RESTful API 에 대해 용어 정리 부터 각 URI별 Json Request Format과 Response Format 그리고 다양한 언어로 구현된 예제까지 풍부한 구성으로 제공되고 있습니다.

지금 바로 http://bluehouselab-sms-openapi.readthedocs.org/ 에서 확인해 보세요.



그리고 GitHub 에 공개된 예제 코드들은
https://github.com/BlueHouseLab/sms-openapi 에서 확인 해보세요.

2014년 9월 현재 C#, C++, C, Java, Node.js, PHP, Python, Ruby 그리고 Bash 환경에서 간단하게 테스트 할수 있는 curl 예제 까지 다양하게 제공 되고 있습니다.

추후 기술 블로그를 통해 하나씩 설명해 드리겠습니다.
이 문서랑 예제만 보고서 무언가 구현하는 것이 가능하겠다 생각이 든다면 당신은 진정한 개발자!

May the code be with you ...

sms   openapi  

---

• «
• 1
• 2
• 3
• 4
• 5
• »