IBM API Management 를 활용하여 API 작성(등록) 하기

안녕하세요 이정운 입니다.

지난번에 올렸던 IBM API Management 를 활용하여 실제 서비스를 어떻게 수행하는지 따라서 해보고 싶다면 하단과 같이 각 step 별로 자세하게 설명된 Tutorial 을 제공하오니 하단의 링크를 참고하시면 됩니다.

IBM API Management Tutorial
https://developer.ibm.com/apimanagement/docs/tutorial/

그런데 영어가 아직 익숙치 않으신 많은 개발자 분들을 위해 간단하게 해당 내용과 거의 유사하게 IBM API Management 를 활용하여 API 작성(등록)하기 강좌를 한글로 만들어서 정리드리오니 참고하시기 바라겠습니다.

IBM API Management v4.0
API 작성(등록)

1) API 작성(등록) 하기 

0. 참고 링크 :
http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.apionprem.doc/api_create.html

1. 본인에게 부여받은 ID/Password 를 사용하여 IBM API Management 콘솔에 로그인을 수행합니다. 

2. IBM API Management 관리콘솔에 접속이 정상적으로 수행되었다면 API 를 작성하기 위하여 왼쪽에 있는 API 메뉴를 클릭합니다.

3. API 세부 메뉴가 나오면 + 아이콘을 클릭하여 나온 리스트 중에서 작성을 클릭합니다.
(Swagger 2.0, WSDL 을 가지고 바로 import 형태로 API 를 만드는 경우에는 해당 메뉴를 사용하면 됩니다.)

4. 새 API 추가 마법사 화면이 나오면 이름, 기본 경로, 버전, 설명등을 적절하게 넣고 추가 버튼을 클릭합니다.

5. 해당 작업을 정상적으로 수행했으면 하단과 상세 설정 메뉴를 확인할 수 있습니다. 

6. 우선 기본적으로 Settings 를 살펴보도록 하겠습니다. 여기서는 해당 API 의 단계를 설정하는 메뉴와 개발자 포탈에서의 테스트 허용 여부, CORS 사용 여부, 스키마등을 설정할 수 있습니다. 

7. API 의 단계는 API 디자인 단계의 레벨 or 구현 정도를 정의할 수 있으며 “Identified” – 아직 완벽히 디자인 되거나 구현되지 않았고 개념적으로 작성된 단계, “Specified” – 내부적으로 완벽히 디자인 되었지만 구현은 되지 않은 단계, “Realized” – 구현된 단계, 세 가지 단계를 선택할 수 있습니다. 다음으로 “Enforce this API” 설정은 API Gateway 에 적용여부를 의미하며 이를 해제하면 API 를 읽는 것만 가능하며 실제 실행은 되지 않습니다. (API 는 Swagger 형태로 export 가능)

8. Settings 에서 ‘Allow this API to be tested’ 체크를 on 하여 API 테스트를 가능하게 하고 http 도 스키마에 추가 합니다.

9. 다음으로 보안 메뉴를 확인해보면 API 보안 스키마와 보안 요구사항에서 클라이언트 ID 가 기본적으로 추가된 것을 확인할 수 있습니다. 

10. 조작을 클릭하여 REST 형태로 호출할 경로와 메소드를 선택하고 추가 버튼을 클릭합니다. 예를들어http://192.168.225.10:9071/loans/v1/quote?loanAmount=20000& annualInterestRate=0.9&termInMonths=52 이런 API 를 호출하는 형태라면 /loans/v1 은 API 경로로 등록했으니 /quote 를 포함한 뒤만 넣어주면 됩니다.

11. API 가 추가되면 조치 밑에 있는 수정 아이콘을 클릭합니다.

12. 경로에서 입력된 값을 기준으로 자동으로 매개변수가 설정되는 것을 확인하시고 필수 여부를 체크하고 설명을 추가 합니다.

13. 추가적으로 필요한 요청 헤더가 있다면 입력을 하고 응답에 대한 결과 예제를 추가합니다.
(응답 예제의 경우 향후 개발자들이 API 를 사용할 때 참고할 목적입니다.)

14. 구현 항목으로 이동하여 + 버튼을 클릭하여 필요한 조작을 선택합니다. (여기서는 기본적으로 프록시 형태의 API 등록을 가정하여 프록시를 선택하도록 하겠습니다.)

 
15. 추가된 프록시 구현에 URL 을 입력합니다. 

참고 #1 : 만약 해당 API 가 Proxy 만 사용할 예정이며 다른 결합(assemble) 이 없다면 하단에서 구현의 어셈블을 사용하지 않고 프록시만을 사용해도 구현이 가능하며 조금 더 나은 성능을 보여줍니다.

16. 여기까지 했으면 기본 프록시 API 작성/등록이 완료된 것이라 우측 상단의 저장을 클릭하여 해당 작업을 완료합니다.

참고 #2 : 하나의 API 에 여러 Operation(조작) 을 사용해야 하고 기 지정된 proxy URL 을 바꾸고자 하면 수작업을 여러번 반복합니다. 이러한 작업을 조금 더 편리하기 위해서 API 단위로 properties(특성)을 하단과 같이 추가할 수 있습니다. 

이렇게 추가된 특성은 하단과 같이 변수처럼 사용가능합니다.

2) Plan(계획) 작성 및 API 등록하기  

참고 : Plan(계획) 이란?
API 는 하나 이상의 계획을 공개하여 개발자 포털에 표시됩니다. 계획은 하나 이상의 API에서 자원 또는 오퍼레이션의 콜렉션을 사용 가능하게 합니다. 애플리케이션 개발자는 개발자 포털을 통해 애플리케이션을 등록하여 API에 대한 액세스 권한을 얻고 계획에 액세스합니다. 

계획은 같은 버전인 하나 이상의 API에 대한 자원 서브세트 또는 API 자원을 그룹화하는 메커니즘을 제공합니다. 자원을 선택할 때 포함할 HTTP verb를 지정할 수도 있습니다. 예를 들어, 하나 이상의 API의 모든 자원에 대한 모든 HTTP GET verb를 하나의 계획에 포함하도록 선택할 수 있습니다. POST, PUT 및 DELETE는 백엔드 서비스에서 더 많은 자원을 사용하는 경향이 있으므로 이러한 verb에 대해 더 많은 비용을 부과하고 이들을 하나의 계획에 포함하도록 선택할 수 있습니다. 

계획에 대한 비율 제한 정책을 설정하여 지정된 기간 동안 애플리케이션에서 작성할 수 있는 요청 수를 지정할 수 있습니다. 또한 계획에 포함되는 자원에 대한 정책을 구성할 수 있습니다. 계획에는 API-A의 자원 두 개와 API-B의 자원 한 개가 포함될 수 있습니다. 이 계획은 세 개의 자원 각각에 대해 서로 다른 비율 제한을 구성하거나 모든 자원에 대한 공통 비율 제한을 설정할 수 있습니다. 애플리케이션이 이 계획을 사용할 수 있는 경우 애플리케이션이 호출을 수행할 때 DataPower가 이 계획의 개별 자원에 지정된 비율 제한 정책을 적용합니다. 다른 애플리케이션은 같은 자원에 대한 다른 비율 제한을 사용하는 다른 계획을 사용할 수 있습니다. DataPower는 애플리케이션을 해당 계획에 비교하여 계획에 일치하는 비율 제한을 적용합니다. 

특정 개발자 조직 또는 커뮤니티에 계획 공개하여 특정 계획에 액세스할 수 있는 사용자를 제어할 수 있습니다. 계획을 공개하면 애플리케이션 개발자가 개발자 포털에서 계획을 보거나 액세스할 수 있습니다. 

API, 자원, 계획, 환경 간의 관계를 보여주는 그림. 

 
참고 링크 : http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.apionprem.doc/api_plans.html

0. Plan 은 상단의 설명을 참고하시면 되며 좀 더 쉽게 설명하자면 API 의 집합으로 보시면 됩니다. 기존에 만들어둔 Plan 이 있다면 별도 작업없이 해당 Plan 을 사용하면 됩니다.

1. IBM API Management 관리콘솔의 왼쪽 메뉴에서 계획(Plan) 을 선택합니다. 

2. 계획 작성 마법사에 이름을 넣고 추가를 클릭합니다. (등록시에 승인 여부 설정도 가능합니다.)

4. 계획을 처음 생성하면 하단과 같이 등록된 조작도 없고 스테이징된 환경도 없는 것을 확인할 수 있습니다. (여기서 조작은 API 를 의미하며 스테이징 환경은 실제 배치 환경을 의미합니다.)

5. 조작의 + 아이콘을 클릭하여 기존에 만들어둔 API 를 추가합니다. 

6. 하단과 같이 자원이 추가된 것을 확인할 수 있습니다. 

7. 추가적으로 연필모양의 아이콘을 클릭하면 요청 제한 정책을 추가할 수도 있습니다. 

8. API 추가를 했으면 오른쪽 상단의 저장을 클릭하여 해당 Plan 을 저장합니다.

9. 저장이 완료되면 배치를 클릭하여 원하는 스테이징 환경에 해당 계획을 배포합니다.

10. 배치가 완료되면 하단과 같이 배치 대상에 추가되는 것을 확인할 수 있습니다. 다만 여기서는 첫 배포라 배치 대상에서 온라인을 의미하는 녹색 동그라미가 아니라 회색 동그라미를 확인할 수 있습니다. 

11. 배치가 완료되면 API 메뉴에서 해당 API 를 클릭하여 상세 부분에서 테스트가 활성화되는 것을 보실 수있습니다. 해당 하는 부분의 테스트를 수행하실 수 있습니다. 

12. 값을 입력하고 호출을 클릭하면 간단하게 테스트를 수행하고 결과를 확인할 수 있습니다.

참고 #3 : 배포하는 environment(환경) 가 Sandbox 가 아니라면 Plan 은 배포하자마자 잠기게(lock) 되며 Plan 버전과 API revision 이 자동 증가됩니다. 이는 배포된 버전을 직접 건드리는 것이 아니라 업데이트된 버전에서 추가 수정을 하는 형태를 가져서 좀 더 안정적인 운영을 수행하기 위함입니다.
이를 다르게 말하면 Sandbox 환경에서는 Plan 을 배포한다고 해도 잠기지 않으므로 개발시점에 적합한 환경이 될 수 있습니다.

참고 #4 : Plan 을 export 하게 되어도 배포와 동일한 현상이 일어납니다. 

3) Plan(계획) 관리 하기 

0. 참고 링크 :
http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.apionprem.doc/task_plan_management.html

1. IBM API Management 관리콘솔에서 관리 메뉴를 클릭합니다. 해당 메뉴를 클릭하게 되면 하단과 같이 방금 배치한 Public Plan 을 확인할 수 있습니다. 

2. 해당 Plan 이 회색의 스테이징으로 되어 있으면 바로 사용할 수 있게 조치 하단의 아이콘을 클릭하여 나온 상세 메뉴에서 공개를 클릭합니다. (처음이라 바로 공개를 한 것이고 기존 공개 계획이 있다면 기존 개획 대체 메뉴를 통해서 추가 설정이나 중지없이 연결성 있게 계획을 공개 가능합니다.)

3. 공개시에 표시대상 등록 대상등을 정한 후에 공개 버튼을 클릭합니다.

4. 공개가 정상적으로 완료되면 하단과 같이 녹색으로 공개가 변경된 것을 확인할 수 있습니다.

5. 이렇게 공개가 되면 실제로 서비스가 가용하며 하단과 같이 개발자 포탈에서 확인이 가능하며 개발자가 해당 API 를 테스트하실 수 있습니다.

4) 개발자 포탈에서 API 사용하기  

0. 참고 링크 :
http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.devportal.doc/con_devportal_storefront.html

1. 개발자 포탈에 접속하여 로그인을 수행합니다.

2. API 를 사용하기 위해서는 애플리케이션을 먼저 생성해야 합니다. 이를 위해서 애플리케이션 메뉴를 클릭한 후 + 버튼을 클릭하여 애플리케이션을 추가합니다.

3. 애플리케이션을 정상적으로 추가했으면 하단과 같이 애플리케이션에 포함된 클라이언트 ID 와 클라이언트 시크릿 등을 확인 가능합니다. (여기서 생성된 클라이언트 ID 와 클라이언트 시크릿은 API Gateway 에서 인증목적으로 사용됩니다.)

4. 이제 사용하고자 하는 API 를 선택하고 실제로 사용하기 위하여 오른쪽 상단에서 계획 선택 메뉴에서 사용하고자 하는 Plan 을 선택합니다.

5. Plan 과 포함된 API 를 확인하고 사용을 클릭합니다. (승인이 필요한 경우에는 담당자의 승인이 된 후에 사용이 가능합니다.)

6. 이제 개발자가 해당 API 를 사용 가능하며 테스트 호출을 해보거나 실제로 Application 에서 URL 에있는 API 를넣어서 호출이 가능합니다.

참고 #5 : 브라우저로 chrome 을 사용하는 경우 첫번째 테스트시에 하단과 같이 경고가 나오는 경우가 있습니다. 

그런 경우 하단과 같이 URL 창의 오른편의 방패 모양을 체크하여 ‘안전하지 않은 스크립트 로드’를 클릭하여 해당 스크립트를 정상적으로 로그하면 됩니다.

참고 #6 : 포탈에서 테스트 말고 직접 테스트를 수행할 경우에 클라이언트 ID 와 클라이언트 시크릿은 하단과 같이 Header 에 추가해 주면 됩니다.

X-IBM-Client-Id=1234
X-IBM-Client-Secret=ABCD

APIM40_guide_01_registerAPI_juwlee201510_v4.pdf