9月27日、サンフランシスコにてAdapt or Dieが開催されました。昨年は、I Love APIで3日コースでしたが、今年は1日に圧縮で、5都市で実施とのこと。先日、Googleが買収を発表したApigee主催のイベントでいろいろ興味深いところです。こちらはそのレポートになります。その1に続いて、クラウドとマイクロサービスセッションをレポート。 Adapt or Die Microservices with Node.js and Docker： 登壇者：Tony Pujals - Director of Cloud Engineering, Appcelerator Microservices and Docker 昨年のイベントでも公演されてました。たしか、node.js系だったかと。今年は、Dockerキャプテンとして。 基本はDocker紹介なんで、Docker1.1.2リリース概要。リリース概要みたら、1.1.3がでてました!! Docker Release Notes Docker Swarmのトポロジー説明。この辺りになってくると、K8との違いを質問する人もおりました。どちらにしろ、この世界は立ち上がり中なので、実際に利用してみるのがオススメです。 Plan for Swarn in Production Serverless Microservices 登壇者：Alan Williams - Enterprise Architect, Autodesk こちらは、Apigeeユーザ企業のAutodeskの人が発表です。Apigee + AWS Lambdaという感じです。 Serverlessのattribute。VMでもコンテナでもなく、コードがイベント要求で処理。 AutodeskのServerlessのバックエンドでAPI提供の事例。こういうのが今後たくさん出てくると思われます。 AWS Lambdaをサポートする、serverless.com あとで、利用してみます。 Serverless.com

9月27日、サンフランシスコにてAdapt or Dieが開催されました。昨年は、I Love APIで3日コースでしたが、今年は1日に圧縮で、5都市で実施とのこと。先日、Googleが買収を発表したApigee主催のイベントでいろいろ興味深いところです。こちらはそのレポートになります。 Adapt or Die Opening Keynote： 登壇者：Chet Kapoor - Apigee CEOなど 開始前の状況。こじんまりとしてますが、良い感じのイベント会場です。 Apigeeパートナー。プロダクトを核にした、エコシステムという感じでしょうか。 Apigeeプロダクトの近々および予定の列挙。 Proxy Chaining Kubernetes Integration Multi Cloud Integration Blockchain Shared flows/flowhooks New Developer Portal Sense Algorithms Federated Gateway GoogleがApigee買収したことにより、Kubernetes 統合が予定されてるようです。オープンソース化されると面白いですね。 Kubernetes Kubernetes: A Microservices Story at Google 登壇者： Allan Naim - Product Manager, Google Cloud Platform GoogleスタイルのCloudコンピューティング。 得られた知見として、オペレーションの切り離し。DevOpsが進むと、NoOps で、Googleで運用したきたコンテナ管理ノウハウを、Kubernetesに展開。これは普通の話。 Kubernetesに統合されるだろう、Apigee EdgeのコンテナクラスタAPIマネジメント構想。コンテナスケジュール管理と配置ディスパッチ、APIリソースパス単位で、必要なコンテナリソースへのアクセスをマネジメントするような構想でしょうか。

RESTfulなAPIを作ろうと思った時の参考になるのが RESTful成熟度の3レベルモデル です。自分たちのAPIがどの立ち位置にあるのかが分かれば、どう改善することでよりRESTfulとして成熟するかが分かるようになるでしょう。 レベル0 まず最初の状態ですが、これは XML-PRC や SOAP が該当するそうです。すなわち、一つのURLと一つのHTTPメソッドで後は送信されるデータで処理内容や処理対象が分かるという方法です。 レベル1 レベル1になると、まずURLが分かれます。しかしHTTPメソッドは変わらず一つです。例えばURLは行う処理によって分かれるものの、HTTPメソッドはすべてPOSTにするといった具合です。PUTやDELETEといったHTTPメソッドが活用されていない状態とも言えます。 レベル2 レベル2になるとURLが分かれているのはもちろん、メソッドも分かれます。CRUD（GET/POST/PUT(PATCH)/DELETE）に分割され、いわゆるRESTfulな状態になります。理想的なAPIとしてAmazon S3を挙げています。 レベル3 ではレベル3とは何でしょうか。それはAPIのレスポンスにハイパーリンク情報を持つことだと言います。例えばAmazon S3のレスポンスにはキー情報は含まれていますが、そのファイルをどういうURLで取得できるのかと言った情報は含まれません。開発者はドキュメントを読み、一定のルールに従ってURLを生成する必要があります。著者であるMartin Fowler氏によれば、Amazon S3はAPIとしては良くできているが、HTMLから学んでいないとのことです。 対してNetflixのAPIレスポンスではリンク情報が含まれており、APIがハイパーメディアとして動作します。これはHATEOASやHALに則った仕組みになります。そうすることで、開発者はどういったURLにアクセスすべきかというロジックを知らなくともAPIを利用できるようになります。 現在、殆どのAPIはレベル2になるでしょう。より利用を広めたり、使いやすいAPIを目指すのであればレベル3を目指すべきです。つまりハイパーメディアの考えを取り入れ、リソースを利用する際に開発者の負担を減らし、より柔軟な連携を実現しましょう。 JWTUMOIM: Act 3

JSONがAPIの基本フォーマットとも呼べる存在になって久しいですが、それによって逆にJSONが持つ緩さが問題になるケースがあるようです。そのため、多くの拡張フォーマットが作られています。 今回はその一つ、JSendを紹介します。JSONフォーマットに一定のルールをつけるだけでぐっと使いやすさが増すことでしょう。 JSendの基本フォーマット JSendのごく基本的なフォーマットは次のようになります。 { status : "success", data : { "post" : { "id" : 1, "title" : "ブログのタイトル", "body" : "ブログのコンテンツ" } } } 明確なルールは2つです。 1. statusを持つ APIのレスポンスを判断するためにstatusというフィールドを必ずつけます。これは3つの値を取ります。 値 説明 必須のキー オプションキー success 処理が成功 status,data fail 処理が失敗 status,data error システムエラー status, message code,data statusは必ずありますので、それを見れば処理が成功したのか失敗したのかがすぐに分かる訳です。 2. dataを持つ success/failの場合はdataフィールドを持ちます。処理が成功した場合には、ここにデータが入ってきますが、直接構造が入るのではなくpostのようなモデル名が入ります。もしこれが一覧の場合は次のようになります。 { status : "success", data : { "posts" : [ { "id" : 1, "title" : "ブログの件名", "body" : "ブログのコンテンツ" }, { "id" : 2, "title" : "別なブログの件名", "body" : "別なブログのコンテンツ" }, ] } } data以下のモデル名があることによって、複数のモデルを一回で返すといった仕様変更があってもすぐに対応できるようになるでしょう。 削除処理のように返すdataがない場合はnullを返します。 { status : "success", data : null } dataフィールドは必ず用意するのが原則です。 エラーの場合 入力エラーなど、アプリケーション側で発生させるエラーの場合は次のようになります。こちらはdata以下に入ります。入力エラーの場合にはエラー箇所が分かるようになっていると便利でしょう。 { "status" : "fail", "data" : { "title" : "タイトルは必須です" } } 対してシステムエラーが起きた場合は次のようになります。 { "status" : "error", "message" : "データベースに接続できません" } もちろん、JSONは返しますがHTTPステータスコードと組み合わせてエラーを作るべきでしょう。 JSendは制約が強くない分、導入しやすいかと思います。一定のルールに沿って提供されることで開発者にとって使いやすいAPIが提供できるでしょう。特に処理の成功、失敗、エラーが明確に分かるのは良さそうです。 JSend

xTech is the keyword for which we at the API team advocate. Now, we would like to present an overview of the concept. What is xTech? As of late, the buzzword "FinTech" has been making the rounds. This term was coined by combining the terms "finance" and "technology." Other well-known examples of the same type of term include AgriTech (agriculture + technology), EdTech (education + technology), and AdTech (advertising + technology). xTech is a general term for these portmanteaus of "________" + "Technology." What is the connection between xTech and APIs? So, how are APIs used with respect to xTech? APIs can be said to be the technological basis for almost every measure. APIs are used not only for inter-enterprise collaboration, but also for cases such as when multiple enterprises need to combine data, and when one company is adding content to its own services. If tasks such as these are not automated, the costs can increase, to the point that it defeats the purpose of adding value. This is not about bringing up the term "API" for just any old reason; APIs exist as an essential aspect of xTech. Why xTech now? FinTech, AgriTech, EdTech, and so on; what might be behind the appearance of so many xTech keywords? The normalization of a lifestyle in which, due to technological development and the popularization of smartphones, the internet has taken on a central role is thought to be one factor. Also, along with smartphones, sensor devices that interface with the "Internet of Things" exist in great numbers. It is said that in the course of our daily lives, data is generated moment by moment from our use of smartphones and web browsers, as well as from sensor devices. As the data collected in this way interacts with the conventional market, new forms of added value are coming into existence. Devices and sensors are appearing that can be put to use not only in fields such as AdTech that had been centered around technology all along, but also in domains such as education and medicine that had been largely unconnected to Internet technology. What We Need To Do? Those people whose work is connected to xTech can be divided into two main categories. The first group is comprised of people in the field of technology. By exerting influence on other markets, people working in technology have the chance to seize great opportunities such as API development, and collaboration with other enterprises. That being said, in some other markets, the investments being made in technology are not great, and there is a need to see examples of API management services being used for more agile implementation compared to developing from scratch, as well as successful demonstrations of starting small. There is also a major shortage of knowledge of other markets within the technology field, and as such, there is a need to study and understand them. The other group is comprised of those enterprises involved in fields such as agriculture, education, and medicine. For many of these enterprises, it is common for business to go well enough with traditional workflows, and there has to be a strong desire to further improve, expand, and develop new revenue streams. However, as knowledge of technology in these fields is insufficient, it may be good to start by consulting with a local system integrator or other expert. In this regard, what likely matters is not whether the enterprise is big or small, but whether it proactively undertakes efforts to move forward, and whether it has knowledge of xTech. xTech is a movement that began from last year. As it is only in its early stages, the next couple of years will likely see the arrival of new services and precedents. By all means, please join us in striving to take part in this movement.

In the last article, we discussed a summary of xTech. In this time, we write about what different fields there are. Use this list to check if there is a market developing around your field. Note that these names are not definite and may vary at times. FinTech This one needs no introduction: financial services mixed with technology. This field has shown major growth over the last few years, centered around banks. In many cases, individual contracts are required for API disclosure. A new economy is being built by FinTech firms. RetailTech The domain of logistics and inventory/warehousing. The field of logistics uses systems for efficient shipment, redelivery requests, etc. Advanced levels of technology were already in place in this area. In addition, use of big data accumulated in this area may allow for the creation of new services. MarTech Marketing paired with technology. Salesforce is a strong player in this area, with unique API economies and partnerships being built around CRM. Other uses of technology include e-mail marketing, marketing automation, performance measurement, etc. EdTech The education sector -- this field was very far behind in terms of use of the Internet, but tablet-based textbooks are slowly making inroads. MedTech The medical field has strong legal controls in place, but it has been revamping itself over the last few years. This includes remote medicine, simple diagnostics through AI, and the provision of medical care to areas lacking robust services. HRTech Human resources paired with technology. As with education and medicine, fields hinging on human interaction still tend to take an analog route. We are seeing changes in the way hiring is performed, with the use of data to visualize various metrics. LegalTech As the name suggests, this is the legal field. With global businesses on the rise, there is an increased need for responding rapidly to change while observing the laws of each country. Attention is also being paid to putting traditional business processes on the cloud. HealthTech The field of health is constantly drawing attention for technological innovations. Sensors can be used to monitor individual vital signs, with advice being given based on changes. AgriTech Agriculture had been behind in terms of penetration of IT technology, but the use of IoT sensors is visualizing data that had otherwise only been understood intuitively. Other efforts include reduced power consumption refinements. FoodTech Food, clothing, and house -- food is one spoke in this trio, and technological innovation is being explored here. Efforts are wide-ranging, taking take the form of things like home food deliveries and the development of fully-nutritive foods. SportTech Recent developments include wearing data-tracking bands while performing sports and sharing individual performance. Professional athletes are also using technology to visualize performance. FashTech The fashion industry is seeing changes involving the development of new materials and clothing with embedded sensors. Other experiments include futuristic fabrics with colors that change by mood. GovTech Technology in a government context. This largely involves the use of open data. Other activities include improving on and evangelizing about software produced by the government. AdTech Another one that needs no introduction is advertising technology. Since the introduction of search keywords, the advertising industry has been dominated by technology. RETech Real estate paired with technology. This field aims to automate residential loans, sale of used properties, rentals, et cetera. Many services are closely tied to finance. Other tech combinations are likely to grow in the future. It will be interesting to see how xTech ushers in changes to traditional analog markets.

RESTful APIはモデルごとにパスを作成し、IDをつけてCRUDなデータの操作を行えるようにしています。これはとても分かりやすい反面、クライアント側ではレスポンス形式を指定できないという欠点があります。 場合によって欲しいデータが異なる際には ?include=friends のようなパラメータをつけたり、別なAPIを追加したりして対応します。こうした拡張はRESTful APIに比べると打算的で、あまり良い設計になっていないことが殆どです。 そうした問題を解決できるかも知れないのがFacebookの開発している GraphQL というクエリ言語です。RESTful APIではありませんが、こうしたインタフェースを用意しておくのも使い勝手が良さそうです。 GraphQLとは GraphQLはHTTPを使ったクエリ言語と言えます。例えばユーザIDが1の名前を取得する場合は次のようにクエリを投げます。 { user(id: "1") { name } } そうすると結果が次のように返ってきます。 { "data": { "user": { "name": "Dan" } } } GraphQLを受け付けるエンドポイントは /graphql のように一つになっているのが望ましいようです。JSONでクエリを投げて、JSONで結果を返すようになっています。 バックエンドについて バックエンドのデータベースは任意のものが選択できます。MySQL/PostgreSQL/SQLiteなどが選択できます。実装はNode.jsで行われているものが多いようです。 データの更新について GraphQLはデータのクエリだけでなく、データの更新や削除にも対応しています。その際にはMutationという定義を使います。 mutation { addComment( postId: 42, authorEmail: "mark@fb.com", markdown: "GraphQL is clearly a **game changer***" ) { id, formattedBody, timestamp } } データ型を定義する GraphQLではクエリを実行した際にあらかじめ定義したデータ型に当てはめることができます。 type Droid : Character { id: String! name: String friends: [Character] appearsIn: [Episode] secretBackstory: String primaryFunction: String } このようなJSON風の言語を使って定義することで入力値の検証を行ったり、データにメソッドを追加したりすることができます。 GraphQLはクライアント側から欲しいデータを指定したり、データの更新を指示します。サーバ側の実装が減る一方で、クライアント側でロジックを実装する必要があるかも知れません。バランスを考える必要があるでしょう。 RESTfulではできなかった、より細かくデータを指定して取得するということがGraphQLを使うことで実現します。セキュリティ要件などは個別に実装していくことになりますが、技術的に面白いアプローチではないでしょうか。 GraphQL | A data query language and runtime

Swagger定義の管理場所について、 コード上に定義する方法 定義ファイルを直接管理する方法 API管理サービスを利用する方法 と、それぞれまとめました。 1. コード上にコメントとして記述する JavaDocのように、コード上のコメントとしてannotationで記述していく方法です。Swaggerを利用するにあたり、真っ先に思い浮かべるお馴染みの記述方法ではありますが、やはり一長一短があります。 長所 コード自体がリポジトリ管理されることで、APIの記述を別に管理する必要が無い。 *開発時にAPIのドキュメントの整合性が保たれやすい 短所 運用時においてはメンテナンスが行いにくい。 新規開発時なら導入はスムーズだが、すでに外部記述となっていた場合には相応のコストが掛かる。 annotationのコード補完が、エディタに備わっていない。 コード自体が長くなり、見通しの面ではデメリットになる。 メリットは傍受し、デメリットは工夫してカバーしていきましょう。 2. 定義ファイルとして記述する Swaggerの定義ファイルそのままを、ファイルで管理する方法です。一見、JSONをそのまま扱うので、デメリットしかないように感じますが、定義ファイルを分割することで、冗長的な記述を抑えるメリットがあります。 もちろん、定義ファイルを一意性を考えずにそのまま記述してしまうと、同じデメリットが発生します。これは、小規模のAPIであれば、問題は有りませんが、大規模APIとなると修正コストが問題になるでしょう。 分割したSwagger定義ファイルが増えると見通しの面では不利になりますが、メンテナンス面では改修を行うに当たって精神的にも楽になるでしょう。 実際にSwagger定義ファイルを分割して管理するツールは、執筆の現時点（2016-08-31）で存在していないと思いますが、いわゆるJSON定義を分割する方法ですので、以下のようなツールを利用してJSONを置き換える事が可能です。 whitlockjc/json-refs Swagger定義ファイルの分割については、また別の機会に紹介したいと思います。 3. APIサービスを使って記述する 各API管理サービスについても、Swagger記法が主流となりつつあります。既にAPIの管理サービスを選択するにあたり、Swagger記法があるかないかが導入の判断に関わることもあるでしょう。ここでは、Swagger定義ファイルがインポート＆エクスポートできるツールを紹介します。 Swagger Editor Swagger定義を管理できる、WEBサービスです。 Swagger Editor ツール自体は公開されています。プロジェクトで運用するのも選択の一つです。 licenseは、『Apache License, Version 2.0』となっています。 swagger-api/swagger-editor: Swagger Editor AWSの『API Gateway』 AWSの API Gatewayを利用しているのであれば、Swaggerのドキュメントを出力できます。 また、API GatewayにはImport機能も備わっており、 どちらもASW用に拡張機能の記述もできるようなので、AWSだけで記述を完結するようにした方が良さそうです。 今後のSwagger定義ファイルの管理 別の記述方法としてAPIBlueprintがあります。記述はAPIBlueprintで出力はSwaggerのJSONファイルで対応するという選択肢も出てくるかも知れません。 Swagger APIによる記述においては、様々な場所で開発できるのも強みであったりしますが、「開発とAPI定義がもっと便利にシームレスにできないか？」と思うところがあります。Swaggerの定義ファイルを管理するのは、API開発において避けては通れなくなってきています。今後もSwagger管理についてはウォッチしていく必要がありそうです。

8月25日、TAM CoworkingにてEnterprise APIs Hack-Night #6が開催されました。今回のテーマはEdTech×APIで、教育分野にフォーカスして3人の方に登壇いただきました。こちらはそのレポートになります。 講演1：プログラミング教育による破壊的イノベーション 登壇者：小金井市立前原小学校 校長 松田 孝様 一言に教育といっても色々と概念があります。学校教育に注目が集まりますが、家庭教育、生涯教育、社会教育などあります。学校教育は一部に過ぎません。さらに学校教育の中でも義務教育は一部で、私学では様々な試みが行われています。だからこそ、逆に公立は手つかずのブルーオーシャンと言えるかも知れません。 幸い私が校長を務める小金井市立前原小学校では私が率先していることもあり、多くのチャレンジが行われています。今回はそんな現場の生々しいとも言える現状について紹介したいと思います。そういった内情を知らずに「イイモノ」を作っても使ってもらえませんので注意してください。 まず公立学校の現状です。教室を見ても分かる通り、そこにはICT、IoT、プログラミングなんて言葉は全く感じられません。かろうじて液晶テレビとエアコンがあるくらいです。昔と何も変わっておらず、「子供たちはランドセルを背負って過去にタイムスリップしている」なんて言われたりします。 そんな時代との乖離を教えてくれたのはタブレットです。私がいた愛和小学校の時、一人一台のタブレットを導入しました。現在、タブレットを入れているのは大阪などの方が多いが、学力調査は東北地方のが高いです。残念ながらタブレットの利用が教育水準を引き上げているという訳ではありません。 学校とは本来、最先端の技術を学ぶ場であったと考えています。今から20年後、2036年の教育現場を思い浮かべてもロボットが所狭しと動いている姿は全く思い浮かびません。学校の中と外では40年のギャップが存在するとまで言われています。それはなぜかというと、保護者の評価基準は自分たちが受けてきた教育にあるのです。「懐かしい」と言って喜ぶ姿がまさにそうです。これでは進化がないのも納得してもらえるでしょう。 ではどうしたら良いでしょうか。そのためにはまず学校と政府、自治体などの関係から見ていきたいと思います。 まず学校の設置者は誰かということです。これは3つあります。 - 国 - 地方公共団体 - 学校法人 公立学校教員を採用するのは誰でしょうか。これは都道府県です。ただし政令指定都市は別です。 次に都の教育委員会と地方の教育委員会、偉いのはどっちだと思いますか。採用、つまり人事権は都の教育委員会にあります。しかし実際の教育は地方の教育委員会が決めています。 さらに教育課程は誰が決められるか。年間の授業日数はあらかじめ決まっていますが、その内容である教育課程の編成権は学校長にあります。学校長はそういった権限を持っており、実は職員会議のようなものは開かなくても良くなっています。 他にも学校を取り巻くステークホルダーはたくさんいます。 - 教職員 - 教育委員会 - 保護者 - 子供 - 同窓会 - 地域 - 議会 これらのステークホルダーの関心事はばらばらです。校長先生が変わったことをはじめると、一定数の保護者はそれに反発するでしょう。それは議会に届きます。彼らは票が欲しいので、保護者の言うことを聞きます。そして議会は教育委員会に通達し、さらに人事権を持った議会によって校長は行動を制限されると言った具合です。そうした様々なステークホルダーによって外からの刺激が届かなくなっているのが現状でしょう。 過去において電子黒板のようなICTが導入検討された時期がありました。しかし全く使われていません。これは幾つかの理由があります。まず先生はとても忙しく、変化を好みません。また、既存教科の完結性や完成度がとても高いため、隙がありません。その結果、必要性や現状との親和性が低いために導入が進まないのが実情です。 そんな中、プログラミング教育は現状の問題を打破する最高の武器と考えています。プログラミングは子供たちにとってゲームのようなもので、楽しんで行っています。そしてプログラミング教育を通じて既存教育の問題を知っていくのが良いと考えています。 学校は勉強する場ではなく、自分で学び、仲間と学び会う場です。それがプログラミングによって実現しています。ロボットを使ったプログラミング教育によって、プログラミングが自分たちの世界を便利にしていくと言うことを実感できています。 最近、プログラミング必修化を巡る動きが幾つも行われています。有識者会議もあります。ただし時間数は各学校で決定となっており、ちょっとやって終わりと言った学校もあります。また、最近の会議では英語教育がメインになっており危惧しています。 今後、教師は単なるティーチャーからファシリテーターへと変わっていくべきだと考えています。 官民連携による「教育×クラウド」 登壇者：NTTコミュニケーションズ株式会社 第三営業本部 稲田 友様 世界のEdTechはどんどん進んでいます。数億円の資金調達であったり、買収も多数行われています。 そんな中、日本の現状はどうなっているのか紹介します。 現在、オンライン教育のプラットフォームを開発しています。その位置づけは「世界に先駆けて社会課題を解決するビジネスを生み出す。バーチャルデータのプラットフォームでは出遅れた。第二のリアルデータでプラットフォームを確立する」とされています。政府も危機感を持ち始めています。世界最先端IT国家創造宣言を出し、家庭と学校がシームレスにつながる教育環境を作ろうとしています。 ではそんな中、実際の教育現場ではどうでしょうか。まず大きな試みとしてプログラミング教育があります。一人一台の環境整備が進められています。例えば柏市で29年度からプログラミング教育を行われます。 国が行っているのが先導的教育システム実証事業です。教育クラウドプラットフォームはクラウドベースで、一人一台のタブレットを導入しています。総務省と文部科学省が連携し、APIを使ったアプリ連携なども行われています。 教育クラウドプラットフォームはいつでもどこでも学べる環境、さらにマルチOSやブラウザ、200以上のコンテンツにシングルサインオンできるシステムです。日本国内だけでなく、海外の日本人学校にも提供しています。教材はHTML5で作られています。自宅に帰ってからの学習も補助でき、動画を見た上で問題を解くといったこともできます。 今の計画ではオープンアーキテクチャでモジュール化していこうとしています。そんな中ではコンテンツとユーザが肝です。つまり開発者の皆さんが頼りです。コンテンツを充実させていき、学びが続いていく環境を作っていこうと考えています。 アナログからデジタルを見直す事例があれば教えてください 最終的にユーザが自分でデジタルがいいか、アナログが良いかを選択しています。それぞれが自分にとって一番良い残し方を選んでいます。実物があるという感覚が大事という人も多いです。 各学校で提供しているコンテンツは一緒ですか？ コンテンツは学校ごとに自分たちで選択して決めています。 オープンアーキテクチャは一般デベロッパーが参加できますか？ すでに公開されています。認証情報を含めて公開されています。 このプラットフォーマーは誰ですか？ 国のスタンスは民の中で広めていって欲しいという考えです。我々、NTTコミュニケーションズでも提供していこうとしています。仕様を考えるのは今は国と我々ですが、最終的には団体を作る予定です。 講演3：制作現場からみた「EdTech業界」 登壇者：株式会社エレファンキューブ代表取締役　支倉 常明様 学校だけではない教育現場を紹介します。これまでの経験で、3つのEdTech業界があります。 - 企業研修 - 子供向け - 個人の学び まず企業研修です。eラーニングは2000年代初頭にはじまりました。2005年には下火になり、2008年にはリーマンショックで一気に教育予算が減りました。その後ですが、市場は落ち着きつつあります。特に市場規模が縮小した訳ではありません。また、動画の活用が非常に増えています。従来は教材をインタラクティブに作っていたのですが、動画によって制作コストは小さくなっています。一言で言えばつまらなくなっていると言えます。 企業研修のこれからについてですが、革命的なものはなさそうです。このまま定着していくのではないでしょうか。そんな中、個人が持っているスマートフォンを利用した学習が加速していくでしょう。 次に子供向けです。これまでの流れとしては2005年に初のデジタル教科書が登場しました。そしてCoNETSが立ち上がり標準化が進められています。それまでは各社が独自に工夫をこらしてきたので、なぜ標準化しなければならないのかと不満の声もありました。 さらに元々は指導者用が多かったのですが、学習者用へと変わってきています。最近では通信教育各社から続々とデジタル版がはじまっています。また、ロボットプログラミング教材が多数出てきました。 今後についてですが、2020年にデジタル教科書が開始します。とは言え、まだまだ黎明期で何が効果があるかないのか、デメリットは何か分からないのが実情です。分からないから面白いとも言えます。変化のなかった教育現場がダイナミックに変化しています。今後、想像もできない教材や活用例が出てくるのではないでしょうか。 子供向けは企業研修と違って、各関係者の気合いが違います。 最後に個人の学びです。まずスマートフォンが普及し、ネットワークインフラが整ったことで、時間や場所の制約がなくなっています。MOOCsなど、高品質な教育コンテンツにアクセスできる機会が圧倒的に増えました。さらに有象無象の教育アプリがあります。半分以上はダメなものばかりですが、面白いものもあります。 代表的なものとしてはフィリピンの英会話があります。これもネットワークインフラの整備が進んだ結果と言えます。さらに英語さえできれば多くのコンテンツにアクセスできるようになっています。 現状は正直よく分かりません。しかし、これまでの格差（学びたくても学べなかったなど。地域やお金の制約）が是正されてきています。 今後はどれだけ「自ら学ぼう」という意識が熟成されるのか、ロボットやドローン、ウェアラブル端末、機械学習とか新しい技術が学びとどうつながるかが鍵ではないでしょうか。その中で思いもよらぬ革命がおきるのではないでしょうか。Pokemon Goなども技術的には昔からあっても使われ方によって革新的です。 EdTechはまだまだ面白くなると考えていますが、地味な市場でもあります。ダイナミックなレスポンスがなく、すぐには儲からないと言えます。アメリカのように何億ドル調達みたいな話にはなりづらいです。私の周囲でも教育は儲からないという話が多いです。 しかし将来につながる意義は大きいと考えています。個人が自ら学ぶ社会、日本だけでなく途上国への教育機会の提供などが魅力です。世界には話し合いなどせず、いきなり殴り合いをしたり、騙し合いが当たり前と言った社会がまだまだ存在します。そういったところにも教育機会が提供できるのがEdTechなのではないでしょうか。 「そんな方法が！」といわれるような、全く新しい学びの体験を作りたいと考えています。 企業研修で個人のスマートフォン利用が進んでいるとのことですが、会社はそれを望んでいるのでしょうか？ 今まで教育したくてもできなかったところにコンテンツが届けられるようになるんじゃないかと思います。従業員の人たちにマニュアルを読め、というのは難しいです。チェーン店などであれば入社前に動画を見て個々人で学んでもらうこともできるでしょう。通勤時間中に勉強できるのはメリットだと思います。 紙と比べて学習効果はどうでしょう？ まだ結論は出ていないのが実情です。ただデジタル、アナログはあまり関係ないと思います。デジタルのメリットとして過去問のようなものは、すぐに結果が返ってくるメリットがあると思います。 企業研修のモチベーションをどう維持すべきでしょう？ 途中で止めて確認問題を挟むという方法があります。動画を見ず、寝ているだけというを防ぐためです。聞くだけではつまらないので、考えさせてから聞かせたり、危機感を覚えさせてから学習させるのが効果的です。 この後、懇親会が開催されました。その途中、LTがあり私がデジタル教科書の中でも使われているAR技術を紹介しました。ゲームで注目されているARですが、実物の教科書に掲げることでスカイツリーを輪切りにして閲覧できる「動く教科書」であったり、旭山動物園のARReaderなどの事例があります。 ARを簡単に実現できる技術&サービスとしてWikitudeがあり、マルチプラットフォームに対応したARアプリが開発できます。 懇親会では皆さんが教育に関してディスカッションを重ねていました。 EdTechは次のFinTechという記事 もあり、非常に注目度の高い分野であると言えそうです。

Swaggerでドキュメントを記述していて詰まるところが幾つかあります。今回はその注意点を紹介します。 リクエストパラメータは配列、レスポンスはオブジェクト 最も戸惑うのがこの点です。リクエストパラメータは次のように定義します。 "parameters": [ { "name": "serviceId", "type": "string", "in": "query", "description": "サービスID", "required": true }, { "name": "accessToken", "type": "string", "in": "query", "description": "アクセストークン", "required": true } ], 各リクエストパラメータを配列で定義します。inはパラメータをセットする場所で、 query : クエリストリング formData : フォーム header : HTTPヘッダー path : パス body : ボディー が利用できます。 対してレスポンスは次のようになります。 "responses": { "200": { "description": "HTTP経由でアクセスするファイル情報", "schema": { "type": "object", "properties": { "result": { "type": "number", "description": "エラーがなければ0" }, "fileData": { "type": "string", "description": "ファイルのデータ" }, "size": { "type": "number", "description": "ファイルサイズ" }, "version": { "type": "string", "description": "バージョン番号" } } } } } schemaというキー以下に定義していきます。typeはデータ型で、 object array number string integer boolean file などが使えます。 レスポンスが配列の場合の書き方 レスポンスが配列の場合、itemsというプロパティにその内容を記述していきます。これは固定のキーなので注意が必要です。 responses: 200: description: "" schema: type: "object" properties: artists: type: "object" properties: href: type: "string" description: "" items: type: "array" items: type: "object" properties: external_urls: type: "object" properties: spotify: type: "string" description: "" 配列がオブジェクトを返す場合であってもschemaというキーは不要です。これは最初だけにしか使われないようです。オブジェクトの場合はpropertiesというキーに対してデータを定義していきます。 Definitionsの使い分け リクエストやレスポンスの形をDefinitionsとして定義することができます。これは全部で3つ用意されています。 Schema Definitions Parameters Definitions Response Definitions Schemaはリクエスト、レスポンスで共用できます。他はそれぞれリクエスト、レスポンスのみで利用できます。目的に合わせて定義する場所を変更できますが、多くのRESful APIの場合リクエストとレスポンスの形式を合わせるので、結果的にSchema Definitionsしか使わないというのが管理上も楽ではないかと思います。 Definitionsは継承できない 意外と面倒なのが一定の形を定義しつつ、必要に応じてフィールドを追加したいという要望です。しかしDefinitionsを継承してフィールドを追加することはできません。逆説的になりますが、Swagger.jsonを書きやすい形で文書を定義すると綺麗なAPI設計につながるかも知れません。 Markdownが使える、使えない部分がある これはSwaggerというよりもSwagger UIの問題なのですが、項目によってはMarkdown記法が使えたり使えなかったりします。詳しくは Swaggerでのapi開発よもやま話 の34ページ目を参照してください。 Swaggerはきちんとした仕様に基づいて作られてきた訳ではありません。そのため、現在はOpenAPI Initiativeによって定義がまとめられようとしています。仕様が定まれば表示上のツール、エディタの動作についても統一感が生まれて使い勝手が良くなることでしょう。

Swaggerフォーマット（Open API Specification）でAPIドキュメントを作成するとどんなメリットがあるのか紹介します。一つのフォーマットから多彩な展開ができるようになっていると、開発工数を低減や品質向上に大きく寄与するはずです。 ドキュメント Swaggerを使ってドキュメントを生成するのは基本と言えます。多くの方がSwaggerをAPIドキュメントのために使っているのではないでしょうか。Swagger UIのようなツールを使うと、その場でAPIをコールできる機能が付いたドキュメントが生成できます。 現状の問題はあまりフレキシブルな機能をもったドキュメント生成ツールが多くないことでしょう。Swagger UIにもテーマはありますが、まだあまり多くありません。そのため、Swagger UI製のドキュメントはどれも似た雰囲気になってしまっています。 コード Swagger UIを使ったコード生成ツールとしてSwagger Editorが挙げられます。クライアント/サーバサイドのコードを生成可能で、多くのプログラミング言語に対応しています。自動生成なので使い勝手がとても良いコードではないこともありますが、それをベースにラッピングして使いやすいSDKに仕上げることもできるでしょう。 さらにかつてのWSDLのようにスケルトンコードの生成機能をもったライブラリもあります。そうしたツールを使うことで、APIファーストであったりAPIの追加に伴うライブラリメンテナンスコストの削減が実現できるようになります。 モックサーバ SwaggerのベースであるJSON/YAMLファイルはサーバの動作を規定したファイルになります。そこで開発用のモックアップサーバとして使えるソフトウェアがあります。あくまでもモックではありますが、クライアントアプリケーションの開発に役立ちます。 サーバとクライアントサイドの開発が分かれている場合、APIが整っていない状態ではクライアント側の開発が行えずに遅延してしまうことが多々あります。ドキュメントを先に整備することでクライアント側の開発がスムーズになるでしょう。 バリデーション JSON SchemaのようにSwaggerを使ってバリデーションを行うことが可能です。バリデーションは複数パターン考えられます。 クライアントサイドのリクエスト検証 クライアントサイドでデータを送信する前に検証します。これによりUXを向上させたり、サーバ側のアクセスを減らすことができます。さらにJavaScriptによるバリデーションのコードを書かなくて良くなるのでコードの重複、メンテナンスコストを軽減できます。 サーバサイドのリクエスト検証 クライアント側と同様にサーバ側も送られてきたデータの検証ができるようになります。これが大多数の目的になるでしょう。サーバ側でも入力値の検証を行うのは面倒なので、Swagger内で定義されている内容を元に検証できると手軽です。 クライアントサイドのレスポンス検証 さらにクライアントサイドではサーバから送られてきたレスポンスについて検証を行うこともできます。多くの場合、サーバレスポンスは無条件に信用してしまいがちですが、データが欠損してたり仕様と異なることはよくあります。 テストケース Swaggerを使ったテストとしてはAPIサーバの実装が正しく行われているかどうかの検証が大きな目的になるでしょう。これはドキュメント/テストファーストで実装した時に役立ちます。また、定期的に実行することで実装が変わっていないことの検証も可能です。 テストケースを生成するソフトウェアの場合、多くは正常系のテストになるようです。そのため、異常系のテストを行う際には多少のメンテナンスが必要になるので注意してください。 Swaggerのドキュメントを整備することで多くの利用が可能になります。APIドキュメントファーストとも言える駆動型開発で効率的な開発を行ってください。

前回はxTechについて紹介しましたが、今回は主なxTechの種類を紹介します。自分に近い市場があるか、ぜひご覧ください。 なお、各名称については確定していないところもあり、呼び方が異なる場合があります。 FinTech 言わずと知れた金融×テクノロジーです。ここ1、2年ほど銀行を中心に盛り上がってきています。APIの開示には個別の契約が必要な場合が多く、FinTech参加企業によるエコノミーが構築されてきています。 RetailTech 物流、倉庫などを主体とした流通に関する分野です。物流業界は効率的な配送や再配達システムなど、元々高度なテクノロジーが使われています。さらにそのビッグデータを活用することで新しいサービスが生まれる可能性があるでしょう。 MarTech マーケティング×テクノロジーです。特に強いのがSalesforceで、CRMを軸に独自のAPIエコノミー、パートナーシップが構築されています。 他にもEメールマーケティングであったり、オートメーション、効果測定などの分野においてテクノロジー利用が広がっています。 EdTech 教育分野になります。元々かなりインターネット利用が遅れている分野ではありますが、タブレットによる電子教科書など徐々に進められています。 MedTech 医療分野です。法律的な規制が厳しい分野ではありますが、ここ数年技術革新が進んでいます。遠隔地医療であったり、A.Iを使った簡易診断など医療が十分に提供されていない地域において注目が集まっています。 HRTech 人事×テクノロジーの分野になります。教育や医療と同じく、人が積極的に関わっていく分野ではアナログが作業がまだまだ多くなっています。人材活用などにおいてデータをもとに数値化する動きが高まっています。 LegalTech 法律分野になります。グローバルなビジネスが増えていく中で、各国の法律を遵守しつつも高速な対応が求められるようになっています。また、仕業や企業法務などをクラウド化する上でも注目されています。 HealthTech 健康分野は常に注目の高い分野です。センサーを使って個人の状態をモニタリングし、変化するステータスに合わせて適切なアドバイスを行うといったことが考えられます。 AgriTech 農業分野もITテクノロジーがなかなか普及していない分野でしたが、IoTのセンサーと組み合わせた活用によって、これまで感覚でしか分からなかった情報が可視化されたり、省力化が実現しています。 FoodTech 衣食住の一つでもある食に対する取り組みです。宅配のようなものであったり、完全栄養食と呼ばれる食べ物の開発など多彩な展開が行われています。 SportTech スポーツにおいてはバンドをつけて個人の活動量を測定したり、個人の活動をシェアするといった利用が行われています。プロにおいてもパフォーマンスを数値化する上でテクノロジーが活用されています。 FashTech ファッション分野においては新素材の開発やセンサーをつけた洋服、感情によって色が変化する素材など未来的な試みが数多く実施されています。 GovTech 政府関係のテクノロジー活用です。主にオープンデータ系の活動で使われます。また、政府が出しているソフトウェアを改善、啓蒙するような活動も行われています。 AdTech 言わずと知れた広告系のテクノロジー活用です。広告分野はリスティング広告の登場以降、一気にテクノロジー主体になっています。 RETech 不動産×テクノロジーという分野です。住宅ローン、中古売買、賃貸などを自動化します。金融系と密着したサービス展開が多いようです。 他にもxTech分野は増えていくと思われます。旧態依然とした市場に対してテクノロジーがどう変革を起こせるか、xTechは楽しみな動きと言えるでしょう。

私たち、APIチームが提唱していこうとしているのがxTech（エクステック）と言うキーワードです。今回はその概要を紹介します。 xTechとは？ 最近話題になっているFinTechというキーワードがあります。Finance（金融）×Technology（技術）という二つのキーワードを合わせた造語です。同様に、Agriculture（農業）×TechnologyのAgriTech（アグリテック）、Education（教育）×TechnologyのEdTech（エドテック）、Advertisement（広告）×TechnologyのAdTech（アドテック）などがよく知られています。そんな○○×Techという名称を総称してxTech（エクステック）と呼んでいます。 xTechとAPIの関係とは？ ではxTechにおいてAPIはどう使われているのでしょうか。ほぼすべての施策において、技術的基盤になっているのがAPIと言えます。企業間連携はもちろん、複数の企業が提供するデータを合わせたり、自社のサービスにコンテンツを付与するといった場合もAPIを使っています。そういった作業が自動化されなければ、コストが増大してしまって付加価値としての意味がなくなってしまうでしょう。 あえてAPIという単語をあげるまでもなく、xTechにおいてAPIの存在は当たり前のものとして浸透しています。 なぜ今xTechなのか FinTech、Agritech、EdTechなど、なぜ多くのxTechキーワードが生み出されているのでしょうか。それはテクノロジーの発展と、スマートフォンの普及によってインターネットが常時存在する生活が当たり前になっていることが一つのポイントになってくると考えられます。また、IoTも合わせてスマートフォンとともにセンサーデバイスが数多く存在します。私たちが日々生活するだけで、そうしたスマートフォンやWebブラウザの操作、センサーデバイスから刻々とデータが生成されるようになっていると言えます。 そうして集まったデータを旧来の市場にぶつけることで新しい付加価値を生み出せるようになってきたと言えるでしょう。AdTechのように元々テクノロジー主体だった分野はもちろん、農業や教育、医療などインターネット技術とは縁遠かった分野においても活かせるデバイス、センサーが登場してきています。 私たちは何をすべきか xTechへの取り組みは主に2つ考えられます。一つはテクノロジー分野にいる人たちです。テクノロジー分野にいる人たちは他の市場へ働きかけることでAPI開発、他企業との連携など大きなチャンスを掴める可能性があります。ただし他の市場においてはテクノロジーへの投資金額が大きくないこともあり、スクラッチで開発するよりもAPIマネージメントサービスを使った素早い実装、スモールスタートな実証実験が求められるでしょう。また、他市場への知識が圧倒的に不足しているため、まずその市場の学習と理解が必須になります。 もう一面は農業、教育、医療などの分野に携わっている企業です。こうした企業では従来のワークフローでビジネスが回ってしまっていることが多く、それをさらに改善、拡大したい、新しい収益構造を生み出したいという強い欲求が必要になります。ただしテクノロジーへの知識が不足しているため、まず地場のシステムインテグレータなどに相談してみるのが良いでしょう。その際には企業の大小ではなく、先進的取り組みを積極的に行っているか、xTechへの知識があるかといった点がポイントになるでしょう。 xTechは去年くらいからの動きになります。まだまだはじまったばかりで、今年や来年は新しいサービスや事例が登場してくることでしょう。ぜひこの動きに追従し、取り組んでみてください。

今回はAPIのバージョン管理について主なパターンと、既存のソフトウェアで使われるバージョン管理との相違点について紹介します。 パス もっともオーソドックスな方法と言えます。多くの場合、次のようになります。 /v1/users またはバージョン番号を日付で行っているケースもあります。 /2016-06-01/users バージョン番号を持たせるケースの場合、何をもってv2にするかが問題になります。日付の場合、リリースしたタイミング（その日付）を使うので数字の付け方に悩むことはないでしょう。 ただし、これらの方法の場合、 何をもってバージョンを上げるか という問題が常に付きまといます。既存の修正なのか、バージョンアップなのかの区別が判断しづらいということです。できればリリース前にバージョンの付け方をルール化しておくのがいいでしょう。 また、v2を作った場合にすべてのAPIがインタフェースを変える訳ではないという問題があります。usersは変えたとしても、productsやその他のインタフェースはそのままで良いというケースがほとんどでしょう。そうした時に、あるAPIは常に古い日付であったり、逆に更新されていないけれどもバージョンが上がってしまうAPIが出ることになります。 HTTPヘッダー バージョンをHTTPヘッダーに含めるケースがあります。このメリットとしては、パスのように アクセス先を変えないで済む ということです。エンドポイントはAPIのバージョンが上がったとしても変わりません。利用者としては常に同じURLで使えるというのはメリットがあります。 デメリットとしては多くの場合、HTTPアクセス部分は共通化して作られるため、usersはv2、productsはv1といった具合に切り替えるのは簡単ではないということです。特にHTTPヘッダーのような情報は共通化した上で、v1またはv2という文字列で固定されてしまっている可能性があります。 SDKやライブラリです隠蔽する方法も考えられますが、それでもバージョンを指定してもらうというのは余計な手間を増やしてしまうためあまり良いと方法とは言えないでしょう。 クエリー クエリー文字列の中でバージョンを指定する方法もあります。こちらはHTTPヘッダーと同じでエンドポイントは常に同じです。そしてURIのクエリーの中でバージョンを指定します。HTTPヘッダーよりは変えやすい印象です。 この場合、バージョンを固定しておけば返ってくる情報は常に同じという安心感があります。パスで指定するケースに比べて、管理単位が細くなる印象です。 // パスでの指定 /v1/users /v1/products /v2/users // v1とは別なレスポンス /v2/products // v1と同じレスポンス // クエリーでの指定 /users?v=1 /users?v=2 /products?v=1 クエリーでの指定の場合、v=2は存在しないことになります。開発者としては新しいデータ取得法を使いたい場合はv=2を指定し、そうでない場合はv=1を指定することになります。 デメリットとしては共通したアクセスになるので、クエリーでの指定を見てレスポンスを返す分、ソースコードの分岐が増えてしまいます。徐々にソースコードが汚くなるかも知れません。 case params[:v] when '1' // バージョン1を指定した場合 when '2' // バージョン2を指定した場合 end もちろん最初からバージョンアップする前提で作られている場合は綺麗に設計もできるのですが、多くの場合バージョン番号は用意していても使うための仕組みはないケースが殆どです。 一般的バージョン管理との相違 パスにバージョン情報を入れた場合、印象としてはSubversionのような全体でバージョン番号を持ったバージョン管理に近い印象になります。もちろん、更新されていない /v2/productsに対してアクセスがあったら/v1/productsを呼び出すといった形にできますが、利用者としては v1 と v2 で何が違うのかと疑問に思ってしまうことでしょう。ドキュメントにその説明を載せるのも面倒です。 かつてあったCVSの場合、バージョン管理はファイル単位になります。クエリを使った方法はこれに近いものになるでしょう。アクセス先単位でバージョン番号を指定するのはあまり筋が良いとは思いませんが、現実的かも知れません。この場合、アクセス先単位でドキュメントに v1、v2の相違について掲載できるようになります。 Gitのような分散型バージョン管理の考え方をAPIのバージョン管理に適用した場合はどうなるでしょうか。これは2つの考え方ができます。 タグを使った全体の制御 まず大きなリリース単位によってタグを使います。このタグはパスに含めるのが良いでしょう。v1、v2相当になります。 アクセス先単位での細かい指定 さらに細かく動作を指定したい場合はクエリ文字列を使って設定できるようにします。これは次のタグに至るまでの細かいバージョン番号と言えます。基本的にはタグを使ったものだけで十分でしょう。 APIのバージョン管理はあまりうまくいっていないケースが多い印象があります。どのタイミングでバージョンを上げるか、後方互換性をどう維持するか、修正と機能追加の違いは何かといった具合です。 これらは既存のソフトウェアのバージョン管理が参考になると言えます。メジャー、マイナーアップデートなどの考え方、APIの開発計画に合わせてバージョン更新を考えていくのが良いでしょう。多くの場合、一度目のバージョンアップを躊躇してしまうためにずっと同じバージョン番号で更新を重ねてしまうようです。最初のバージョンアップは事前の計画に沿って進めていくのが良いでしょう。

Swaggerはオープンソース・ソフトウェア、オープンなフォーマットと言うこともあり、関連するライブラリが幾つか存在します。OpenAPI Initiativeが設立されたこともあり、業界標準となっていけばさらに登場してくるのではないでしょうか。 今回はそんなSwaggerによる開発を補助するソフトウェアを紹介します。 Swagger2Markup/swagger2markup SwaggerファイルをベースにMarkdownファイルを生成するソフトウェアです。若干癖のあるツールですが、MarkdownファイルであればPDFをはじめとして他のドキュメントフォーマットにも展開しやすくなります。 Markdownフォーマットは他の多くのドキュメントシステムでも使われていますので、そういったシステム向けにドキュメントをコンバートする際にも便利です。 BigstickCarpet/swagger-server: Get your REST API up-and-running FAST with Swagger and Express Swaggerファイルを使ってRESTfulなモックサーバを立てるシステムです。本番環境下ですべてのサービスが揃っていない状態でもクライアント管理がはじめられるようになります。 また、クラウド系サービスにおいてSwaggerファイルを提供することで開発者の環境においてローカルで動作するモックサーバを提供できるようになります。 Swagger UI – Swagger Swagger UIはSwaggerファイルをHTMLで表示するシステムです。HTML上からCRUD操作を実際に行えるのが特徴です。ただしOAuth2トークンなどが必要であったり、認証などを要する場合は作り込みが発生します。 SwaggerファイルをHTMLとして表示したい時にはこのSwagger UIが最も多く使われるようです。 Swagger Editor – Swagger Swaggerファイルの作成、編集を行うのがSwagger Editorです。入力内容の検証ツールも組み込まれているので、ミスしたとしても改善しやすいはずです。ツリー構造の折りたたみ機能もあり、大きなAPIドキュメントでも効率的に編集できます。 Swaggerのフォーマットに精通していないと、テキストエディタで書いた後に検証すると多数のエラーが出るはずです。最初からSwagger Editorを使うことで手戻りを減らしましょう。 Swagger Codegen – Swagger Swaggerでは多数のプログラミング言語に対応したソーコード（スケルトンコード）が生成できます。クライアント/サーバサイドの入力値検証であったり、API利用を簡便化します。 言語によってはソースコードのレベルが高くありませんが、生成されたコードをラッピングして使っても良いでしょう。ドキュメントさえメンテナンスすればライブラリが更新されて最新の状態を保てるというのが理想です。 ReDoc Swagger UIとは別なドキュメントジェネレータです。データ構造が縦に表示されるのが特徴となっています。今の時点ではSwaggerのファイルを読み込んで動的にコンテンツを生成します。今後の予定としてSEO対策のために静的ファイル生成に対応するようです。 画面構成は3ペインで、一番右側にコードサンプルが表示できます。 moongift/cURLtoSwagger: Convert from cURL command to YAML format. Compatible with Swagger. 筆者が作っているツールがcURLtoSwaggerです。cURLコマンドとそのレスポンスを使ってSwagger用のドキュメントを生成します。cURLコマンドはGoogle Chromeの開発者ツールで取得できます。 Swaggerはサービス提供側が記述する場合もあれば、すでにできあがっているAPIからドキュメントだけ書き起こす場合もあるでしょう。cURLtoSwaggerは後者向けのツールになります。 Swagger（OpenAPI Specification）に関連したツールは今後増えていくと予想されます。そうすることでSwaggerのエコシステムはさらに広がっていくことでしょう。API/ドキュメントファーストの開発においてSwaggerは見逃せない存在になるはずです。

JSON has been increasingly adopted as a Web API format. While JSON can be handled easily in light description languages, the trouble it has with assuring data content is viewed as problematic. For this reason, JSON Schema, which defines the structure of JSON, has attracted attention. By providing types and meta-information to JSON data, rules for formatting are added. JSON Schema is currently being developed as a specification. You can check the details at JSON Schema and Hyper-Schema . We’d like to think about what possibilities adopting JSON Schema can bring. 1. Validation The primary one that comes to mind is validation. This can be done for both clients and servers. JSON Schema enables you to verify data before sending and automatically validate data you obtain. If the verification results produce errors, you should probably return them as they are. As usage of data structures and types is assured after verification, you can feel secure when writing code. 2. Create Libraries that Handle Data This is similar to how "Web Service" often automatically generate code from a schema like WSDL. It will automatically generate skeleton code if it’s for Java or .NET, and it will automatically create methods for script languages such as Ruby, PHP, and Python. JSON is often handled with hash and associative array after parsing. However, by generating code in advance, you’ll be able to use it as easy-to-handle data. 3. Generate Documents In addition, since JSON Schema explains parameters and also handles descriptions for data structures and URLs, it can be used for generating API documents, too. Although consistency must be maintained due to separation from the actual code, you can maintain the latest state by combining JSON with testing structures, which will be mentioned later on this page. As there are many developers who refer to API documents, such output should motivate you to properly maintain JSON Schema. 4. Dummy Server JSON Schema can be used as a base for library test servers that handle Web APIs. Although the logic parts of the server cannot be assured, having a dummy server makes local development and operation in a test environment easy. However, while you can check requirements and types of input values on dummy servers, it doesn’t allow you to check logic, such as token validity. Note that it’s better to use it as an auxiliary tool during development. 5. Automating Test Also, JSON Schema can be used for operating tests for a Web API itself. Post the pre-defined values, and you can verify whether the expected results will be produced. Systems that previously used Web APIs may suddenly stop working, for instance, when new required fields are added to extend the Web API. Also, in such circumstances, it is important for JSON Schema to manage versions and check whether it’s continuously operating with all versions. After software that uses a Web API is complete, the software often enters an automatic operation phase. In order to ensure results even in such circumstances, JSON Schema can be useful. 6, Error Check During Development With IDEs and such, adopting JSON Schema enables you to display advance warnings. The JSON structure has low readability when kept in text form, and it is often read incorrectly. JSON Schema could be useful to prevent these mistakes. Although JSON Schema has several merits, because it was originally developed to stay away from the complexity and nuisances of WSDL and such, it has not been widely adopted. However, it will turn into an important element, as Web APIs will be used more and more often at the enterprise companies. Rather than just being something that you should do, I believe JSON Schema will be used more if it can improve development productivity and reduce burden, for example, by automatically creating documents using JSON Schema.

When you will mash up APIs and create a new service, you have to first find an API providing the data that you need. In this installment, I summarize services offering directories of APIs. PublicAPIs As of this writing, this indexing service lets you search 5,330 APIs. You can find out APIs, and also register new APIs in the system. PublicAPIs | Directory of public APIs for web and mobile API For That APIs are indexed across approximately twenty categories that include social networks, finance, and more. There are close to three hundred categories. API For That | An API Directory Zapier The service functions like an enterprise version of IFTTT. Users link two services to trigger actions. The Explore menu lets you access a wide range of APIs (limited to those supporting Zapier). The best apps. Better together. - Zapier ProgrammableWeb This site provides API directory information and news. Over 13,000 APIs are offered. While there are few Japanese APIs, if you plan to search APIs worldwide, this site is the best. ProgrammableWeb - APIs, Mashups and the Web as Platform Mashup Awards You are seeking a Japanese API, check the Mashup Awards API list page for a comprehensive list. You will also find overseas APIs, with close to 250 APIs indexed. APIリスト | MA【エム・エー】 by Mashup Awards When you want to poll GPS information like weather or hotel information, you will get better fidelity by using an API from the target country. At the same time, linking two APIs may yield unexpected potential and results. Settling on what you want to build before searching for APIs is one technique, but you could also go in reverse, looking at these lists and getting inspiration from what you find.

What are the challenges and advantages of enterprise API utilization? In order to get a grasp of the situation, we conducted an interview with Mr. Kato, an API gateway developer. The interviewer is Nakatsugawa from MOONGIFT. What are the API gateways you planned from 3 years back? With 10 years having passed since the popularization of Web APIs (hereinafter referred to as “APIs”), there has been a movement in these past few years among businesses to increase the competitiveness and utilization rates of services by making APIs open. We at NTT Communications have also API-tized our services and are trying to promote their use. Rather than creating a separate API for each service, API gateways refer to attempts to provide an easy-to-use API that standardizes them and unifies management. A number of similar services have become available in these past one or two years. We planned it about 3 years ago when we carried out a technical verification and launched the project, and it became an officially released service from April this year. The actual development period was only about 6 months as we had made some progress beforehand on technical verification. API management services already starting overseas Carriers such as AT&T and Verizon are already starting. There are three primary reasons why carriers are making progress. They have a wide range of services Customer loyalty is improved by providing these services through a common interface It serves as a technical cushion for a wide range of sectors As an example of problems that can arise when there is no API management mechanism – although this was not APIs – there was a period at NTT Communications during which each department developed smartphone applications freely without any company standards. As a result, there was no sense of uniformity among interfaces and overall quality, which was confusing for users. In order to prevent similar problems from occurring with APIs, we thought of 2 measures. API gateways API checklists API checklists define how APIs are to be develop, rather than just develop them. APIs can be made so long as you have the technical capabilities. However, how to best make them is where differences of opinion arise among the people involved. It is for this reason that we created an API checklist as a unified standard for things such as interface, security, data format, etc.. One point that we were particularly careful about was to use JSON Schema that enables automation or JSON format schema check, a lightweight format based on REST API rather than SOAP. By sticking to these guidelines, we believe that we can create APIs that our clients have no problems with. ※ Please refer to the following article for more on API checklists (Japanese articles). Things that should be kept in mind in order to design a proper API: Interface Data format Version control, synchronously or asynchronously Security API provision with regard to enterprise can be thought of as the opening up of in-house systems. As there are user limitations in conventional business systems, it is not too much of a problem even when services were temporarily suspended for things such as maintenance. However, as API-tization of these systems means they will be used for automation from outside, things such as down time and information freshness can become a problem. Taking these points into consideration, and as it needed to be system development, we felt that there was a need to change our way of thinking through a fixed framework. Public was not enough. What was the next step after that? Although many APIs have been made over the past 10 years, there are many cases in which they were simply made and abandoned. In order to prevent this, we believe there is a need for: A presentation of a mash-up example using third-party API Applications, tools, and sample codes that use API We are currently thinking of enhancing libraries and mechanisms that support such developments. One thing we often hear from developers who are trying to develop using APIs in reality is that they find it difficult to get a sense of scale. The reality is that the sense of scale varies with the application being made, therefore, we want engineers to train their senses by first writing small lines of code using APIs. Our model is that, instead of trying to tackle a large project from the start, it is best to start off small and slowly work your way up to larger projects. What is the model you aim for with API gateways? First of all, the API-tization of NTT Communications's services is only the first step. For the next step, we are thinking of API-tizing the services of our client companies and engaging in their management and operation. However, as we are now at the stage where we are promoting API-tization in regard to networks and cloud, all in all, we are still at 20%-30%. Additionally, we are also focusing on the IoT market. For example, we believe that API gateways can serve as hubs that stand between IoT devices and developers. Data, threshold values, etc. gathered from devices will be available to the public through the API. Moreover, there are also plans to introduce mechanisms that push information both ways using things such as WebHooks and WebSockets. About 2 years ago, APIs were still at a stage where developers were just starting to get a feel for it. After that, from about last year, the importance of APIs started to be acknowledged, even in the executives. We want to spread the idea that, although it takes time to add an API to an existing service, effects can be increased 2-3 fold while development costs can be kept at 1.1 to 1.2 fold by preparing “API First” from the beginning when developing a new service. That being said, enterprise API utilization still has a long way to go. To address this issue, we, as ourselves and regardless of our relation to NTT Communications, are planning Enterprise APIs Hack-Nights in order to boost enterprise API utilization and make it more exciting. We hold these events regularly so please feel free to participate!

The evolution of the cloud has brought big data and the field of machine learning, which is currently receiving a lot of attention as the next big thing. Actually, machine learning has quite an extensive history, with research beginning back in the 1950s. In this article, we’ve assembled a collection of convenient machine learning APIs for you try out. Prediction API Google’s machine learning service, the Prediction API. Their RESTful API for learning from training data, etc. allows seamless connectivity to Google’s various Cloud Platform services. The API supports Google Sheets as well—use the Prediction API directly from within your spreadsheets! This is a unique advantage that only Google can bring. Specifically, users need to install an add-on called Smart Autofill. We tried it out, and getting predictions is easy. All you need to do is select the needed cells to get your predictions. Smart Autofill Spreadsheets Add On The documentation is mostly in English, but everything is easy to read and understand. The project has only just been open sourced (in November 2015). We’ll likely see more and more information as time goes on. The pricing structure has free and paid versions. The free tier is more than enough to try things out for yourself. See below for the detailed pricing structure. The SLA guarantees 99.9% monthly uptime. See here for detailed pricing information. Documentation Quickstart Microsoft Azure Machine Learning A machine learning service for Microsoft’s Azure cloud service platform. The most impressive feature is its Machine Learning Studio graphical interface, but users can access the platform via both the GUI and API. Free users are only allowed to do staging procedures. To switch to a live operating environment and acquire endpoints, users need at least a Standard Plan (explained later) subscription. The Japanese documentation is largely complete, and both the tutorial and the GIU management information is organized in an easy-to-understand way. There’s an instructional book on sale too—the cost of learning should not be high. The pricing structure is separate from the Azure platform and divided into Free and Standard Plans. The Standard Plan is completely pay-as-you-go and starts in the ¥1000-¥2000 range. See the pricing details page for more information. The SLA states that Microsoft guarantees 99.95% availability of API transactions for the Request Response Service (RRS). Documentation Tutorial Amazon Machine Learning| AWS AWS’s analytics service, Amazon Machine Learning. The documentation is in English and is quite substantial. It is a little difficult to understand, and there are so many services that users may have trouble finding the service they need. After logging in to the console, first try to find the analytics area. At the time of this article’s writing, availability is restricted to the Eastern US and the EU (Ireland). You should get a decent idea of how the specifics work by going through the tutorial. Pricing for AWS is exceedingly difficult to understand, but data analysis and model construction fees are, at $0.42/hour, set higher than other services. For details, please refer to the data analysis and model construction fees . The AWS Amazon Machine Learning service cannot currently be used with the AWS 12 month free tier trial. We almost missed the warning message. Be careful not to miss this when using their product. Documentation Tutorial bigml “bigml” is an API service that offers cloud machine learning and predict analytics services. The GIU is easy to use, and the machine learning doesn’t come off as troublesome. Users can get started right away after logging in. There are several sample datasets prepared. Going through these should give you a general idea of how the platform works. For Web services, bigml provides a fully controllable RESTful API. The documentation is well-supported, and users should not find themselves getting lost. See the documentation here . The pricing starts at a monthly plan option for $30 or a yearly plan that, when paid together, costs $240 (calculates to $20 per month). However, be aware that this pricing can change depending on usage and data volume. indico Users are issued an API key after logging in and can use this key to start coding right away. The platform provides code samples for Python, Ruby, Java, NodeJS, PHP and R, so experienced programmers should have no problem getting started. The below demo is an sample of text sentiment analysis. It includes actual example code that for reference in your own models. The API is free for up to 10,000 calls per month. There is a fee afterwards, but the amount is on the low side. Furthermore, the system currently only supports English, but the machine learning service API is extremely easy to pick up and use. Machine learning has an image of being cumbersome and difficult to handle. However, after trying things out myself, we found that things weren’t as bad as we had thought. We were able to implement algorithms like regression analysis and Bayesian filtering without what felt like too It has become a commonplace and accepted practice for companies to leverage big data to filter data, provide recommendations, etc. The introduced services all have free tiers, so why not give them a whirl when you have the opportunity.

In this installment, I will write about precautions involved in offering an enterprise-level API. With increased use of APIs in BtoB and other enterprise contexts, taking the following points in mind is sure to help you provide a more user-friendly API. 1. Unified API specs and rules When each and every API has a varying interface and data format, the result is confusion among users, and your API will see limited use. While there is no industry standard, recent trends revolve around REST interfaces and data formats in JSON or XML. In addition, a bare minimum of the rules described below in terms of version control and parameter naming conventions should be agreed upon internally before release. 2. Privilege management Privilege management is extremely important in the element of enterprise API. Ordinarily, an API assigns one token per user or is based on the premise of use via a single application. However, in an enterprise context, multiple organizations (users) coexist. For this reason, you must assign CRUD (create, read, update, delete) privileges for each organization and user. For example, members of organization A may be allowed to create data, but they cannot update it. The systems administrator at the company must be able to freely configure these privileges based on actual use. We will be offering privilege administration functionality starting in September of last year in order to offer a more safe and flexible control of API access. Click here for information on privilege administration on the IAM API . 3. Logging While most APIs provide log data on a call level, an API in an enterprise context will need to keep logs on what data was accessed and what functions were performed, both on an API basis and a user basis. This is a must for auditing purposes, and it is critical for exploring the cause of incidents when they occur. Because APIs often span systems, they may be used in unseen ways, including sudden batch processing at night. This perforce requires logging at a fine-grained level. 4. SLA and maintenance response While an API functions automatically, this does not mean you can set it and forget it. Further, periodic maintenance will also be practiced. Therefore, the API must have an SLA and built-in responses and rules for maintenance. In the absence of such agreement, you find cases where services using an API simply return a 500 HTTP status error with no explanation. It is no surprise, then, when concerned e-mails reach the administrator. Implementing thorough error documentation allows the user to respond in the event of a problem. 5. Version control In an enterprise elements, API updates must be performed in a critical fashion, so manage version control based on a specific set of standards. Ordinarily, a version number is fixed to the API endpoint and new and old versions are distinguished in this way. There may be cases where a system is not equipped to immediately work with the latest bleeding-edge version of an API, so design the structure such that new and old versions can be concurrent, without immediately deprecating old versions. 6. Documentation There are a surprisingly large number of cases where APIs lack sufficient documentation. While the provider may consider the literature sufficient, putting oneself in the user's shoes, one finds that the information is often totally lacking. It is not enough to simply convey the information accurately -- the documentation must be neither too skimpy nor too robust, and it must be easy to use. Aim to have your documentation available online. Oftentimes, when setting up a dedicated search server, the result pales in comparison to Google and other search engines, and its usability is lacking. Further, distributing documentation in PDF or similar formats much to be desired in terms of searchability. 7. Libraries/SDKs Another point equally as important as documentation is your libraries and SDKs. You will not simply be providing an API -- you must also have libraries and SDKs corresponding to various programming languages. You can begin by providing ones tailored to the environments in which you want your users to deploy the API, and then roll out libraries and SDKs for other languages. Corporate systems are not composed of a single language, so you will need many libraries and SDKs. Taking future maintainability into mind, aim to keep libraries and SDKs thinly wrapped around the API. The point about documentation applies to libraries and SDKs, too, which should have ample literature and sample applications. 8. Sandbox Lastly, make sure to offer a demo environment for testing the API. Having to immediately update and delete data in a live environment poses too much of a risk to companies. Aim to automatically prep data that is as close to a live environment as possible; ideally, the system should copy data directly from the existing live environment. Being able to test maintenance functionality is also a plus. API-based development is not complete out of the gate. It is something that is continuously updated and added to. For this reason, sandbox environments should not be limited to 30-day trials and the like, but available persistently. When expanding use of an API to beyond one's company and offering it publicly in an attempt to foster new business, there are many considerations to make, the above notwithstanding. In particular, when opening up the stores of data accumulated at your company, a level of management commensurate with that data is needed. It is not simply enough to make the data public -- provide the API only after considering the peripheral technologies and ease of development and use by enterprise users.