IBM Bluemix には Watson や IoT など、数多くの IBM ／サードパーティ API がサービスとして登録されており、利用者はこれらを活用してアプリケーションの高速な開発ができるようになります：



またランタイム（アプリケーションサーバー）とサービスをバインド（紐付け）することで、ランタイムの環境変数からサービスへの接続情報（ユーザー名、パスワードなど）を動的に参照することができるようになります。これによって接続情報を外出しする必要がなくなり、非常にセキュアな外部 API 連携が可能になる仕組みが提供されています：



さて、このような IBM Bluemix 環境において、「標準では登録されていない API をサービスとして利用したい」という要望を（少なくとも自分が知る限りでも何件か）いただいています。もちろんサードパーティ製 API として正規に登録する手順というものもあります。ただこちらは Cloud Foundry Service として最低限必要ないくつかの API（後述）を実装した上で申請し、条件や審査といったプロセスを経て IBM Bluemix サードパーティサービスとして登録されるものになります。この正規の手順について、詳しくはこちらを参照ください：
https://developer.ibm.com/marketplace/docs/vendor-guide/how-do-i-integrate/integrating-bluemix/


一方、いくつかの制約事項がある中で、この申請や審査といった手順を通さずに自身のサービスを IBM Bluemix のカスタムサービスとして利用可能にする方法もあり、以下のブログで紹介されています：
https://www.ibm.com/blogs/bluemix/2017/01/extend-bluemix-service-broker/


上記エントリによると、その制約事項の中で大きなものは以下の４つです：
(1) IBM Bluemix の Web UI には 100% 統合されない
(2) 同一組織の中だけで利用可能なサービスとして登録される
(3) Web API 自体は https で運用されている必要がある（オプション）
(4) 課金の仕組みが必要であれば別途実装する

(1) について補足すると、IBM Bluemix はオープンソース製品である Cloud Foundry をベースに IBM が機能拡張したものなのですが、（あまり知られていませんが）Web ブラウザから操作できるようにしているのも IBM の拡張によるものです（CloudFoundry 自体は cf というコマンドラインツールを使って操作するものです）。この Web の UI は Bluemix のサービスラインナップとも密に統合されており、以下で紹介するカスタムサービスで追加したサービスは Bluemix Web UI には反映される部分とされない部分が出てきてしまいます（例えば追加したカスタムサービスはカタログ画面には表示されません）。基本的には cf ツールを使ってサービスを追加してバインドして・・という手順をとって実行する前提の方法になります。

(2) はカスタムサービスの利用可能な範囲についてです。通常の Bluemix サービスは Bluemix ユーザー全員に公開されて利用可能になりますが、以下の方法で追加したカスタムサービスの場合は同一の組織内（または同一のスペース内）だけで利用可能なサービスになります。異なる組織のユーザーからは利用できない方法であることをご了承いただきます。

(3) はその API 自体が http に加えて https でも稼働する必要がある、という条件です。この (3) に関しては（動くか動かないかだけの条件であれば、http だけでも動くので）必須ではないのですが、Bluemix の Web UI から参照するページの一部が https 必須になっており、https 非対応だとそのページが正しく表示されない、という問題が生じるのでした。繰り返しますがそのページがブラウザから正しく表示されるかどうかと、API として実行できるかどうかは別の問題なので、その意味では必須ではない（が、対応されている方が好ましい）とお考えください。要するにピュアな Cloud Foundry サービスとして認識させるための要件ではなく、IBM Bluemix 統合のための要件であるという意味です。

(4) は今回作成するカスタムサービスは（複数のプランを実装することはできますが）Bluemix 上では無料サービスとして動く、ということを意味しています。課金が必要な場合は正規の手順でサードパーティサービスとして登録いただくか、あるいは別途課金の仕組みをサービス側に実装する必要がある、ということです。


上記のような制約事項がある中で、自分で作った Web サービスの API を IBM Bluemix のカスタムサービスとして統合する手順を紹介します。全体的に長くなりそうなので紹介は３回に分け、第一回目である今回は上記の解説に加えて「自分で作った（IBM Bluemix に統合するためのカスタマイズをする前の） Web サービス API 」の紹介をすることにします。もちろん最終的には皆さん自身で作った API をカスタマイズしていただくことになると思いますが、そのカスタマイズ前の題材の紹介であると理解してください。


Web API は非常にシンプルな、「四則演算を行う API 」とします。今回用意したサンプルは Node.js で実装されています：
https://github.com/dotnsf/dotnsfOperation/blob/master/app0.js


今回対象とする上記コードは以下のような内容です。まあ普通の Node.js + Express による API 定義（/:operation/:x/:y）に加え、/ にアクセスがあった場合の表示と、/doc に簡易ドキュメントを用意しています：

//. app0.js
var express = require( 'express' ),
    cfenv = require( 'cfenv' ),
    appEnv = cfenv.getAppEnv(),
    app = express();


//. Service APIs
app.get( '/', function( req, res ){
  var html = '<title>My Broker</title>';
  html += '<h1>My Broker</h1>';
  html += '<p>ドキュメントは<a target="_blank" href="./doc">こちら</a>を参照ください</p>';
  res.writeHead( 200, [ { 'Content-Type': 'text/html; charset=UTF8' } ] );
  res.write( html );
  res.end();
});

app.get( '/:operation/:x/:y', function( req, res ){
  var operation = req.params.operation;
  var x = parseFloat( req.params.x );
  var y = parseFloat( req.params.y );
  var z = 0;

  if( operation == 'plus' ){
    z = x + y;
  }else if( operation == 'minus' ){
    z = x - y;
  }else if( operation == 'multiply' ){
    z = x * y;
  }else if( operation == 'divide' ){
    z = x / y;
  }

  res.writeHead( 200, [ { 'Content-Type': 'text/plain' } ] );
  res.write( '' + z );
  res.end();
});

app.get( '/doc', function( req, res ){
  var html = '<title>My Operation Document</title>';
  html += '<h1>My Operation Document</h1>';
  html += '<p>This is a document for my operation</p>';
  html += '<hr/>';
  html += '/plus/x/y => return ( x + y )<br/>';
  html += '/minus/x/y => return ( x - y )<br/>';
  html += '/multiply/x/y => return ( x + y )<br/>';
  html += '/divide/x/y => return ( x / y )<br/>';
  res.writeHead( 200, [ { 'Content-Type': 'text/html; charset=UTF8' } ] );
  res.write( html );
  res.end();
});

var service_port = appEnv.port ? appEnv.port : 1337;
app.listen( service_port );
console.log( "server starting on " + service_port );

肝となる API （/:operation/:x/:y）は４つの機能をもち、それぞれ以下のような URI で実装されます：

URI	関数の処理内容	例
/plus/x/y	x + y を実行した結果を返す	/plus/2.3/3 → 5.3
/minus/x/y	x - y を実行した結果を返す	/minus/2.3/3 → -0.7
/multiply/x/y	x * y を実行した結果を返す	/multiply/2.5/-3 → -7.5
/divide/x/y	x / y を実行した結果を返す	/divide/5/4 → 1.25

実際に上記の URI に数値パラメータを入れてアクセスすると、実行結果を（text/plain で）画面に表示します：



また、API とは別にドキュメントルートにアクセスがあった場合のページと、



API の簡易ドキュメントページが用意されています：



ここまでのアプリケーション（というか API）は上記の app0.js をそのまま Node.js で実行すれば動かすことができますので、興味がある方は実際に試してみてください。

そして次回は、この app0.js に対して IBM Bluemix のカスタムサービスとして統合するための変更を加える、その内容や手順を紹介します。IBM Bluemix(Cloud Foundry) のサービスとして利用するためには（サービスのインスタンス化や削除、バインド／アンバインドの仕組みを実現するためには）どのような実装が必要になるのか、といった辺りを紹介する予定です。


（追記）続きはこちら：
http://dotnsf.blog.jp/archives/1064347464.html