はじめに
限られた時間の中で今後WebAPIを使用していくための入門となるよう、「正確」よりも「わかりやすさ」を心がけてみました。
APIとは
Application Programming Interfaceの略。ソフトウェアからOSの機能を利用するための仕様またはインターフェースの総称で、アプリケーションの開発を容易にするためのソフトウェア資源のことをいう。「API」の重要な役割は、サービス提供者が公式に仕様を定義・管理している操作方法（インターフェース）を提供することである。
by 大塚商会 IT用語辞典
https://www.otsuka-shokai.co.jp/words/api.html
APIとは「Application Programming Interface（アプリケーション・プログラミング・インターフェイス）」の略語であり、「ある1つの機能に特化したプログラムで共有可能なもの」や「ソフトウェアの機能を共有する仕組み」のことです。よく使う機能がAPIとして用意されていれば、わざわざ一からプログラムを組む必要はありません。必要に応じてAPIを利用し、効率的に開発を進められます。
c++でのWINAPI使用例
#include <windows.h>
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,int nCmdShow){
HWND hwnd = CreateWindow(TEXT("TEST") , TEXT("これはテストウインドウです。") ,WS_CAPTION ,100 , 100 , 200 , 200 , NULL , NULL ,hInstance , NULL);
if (hwnd == NULL) return 0;
ShowWindow(hwnd , SW_SHOW);
MessageBox(NULL , TEXT("これはテストです。"), TEXT("TEST1"),MB_OK);
return 0;
}
Windows OSの持つ機能が、「CreateWindow」を使用するだけで簡単に自社システム等で使用できます。
Windowは普段当たり前に使用しているでしょうが、移動やサイズ変更できたり、アクティブウインドウって概念があったり、実は複雑。自前で実装するのはとても大変。
それを解決してくれるのだよAPIは。
WebAPIとは
ネットワーク越しに、APIを提供することで、自システムはもとより、他社の作成した機能を自システムに取り込んだり、他社に自システムの機能を提供することが可能に！
従来は、APIといえばOSがアプリケーションソフト向けに提供していた機能を指していたが、現在はWebサービスがアプリ開発者向けに公開している機能を「Web API」と呼んでいるほか、気象情報、グルメ紹介、テレビ番組表、交通データ、観光情報などのさまざまなAPIがある。APIを利用すると、よく使う機能をAPIから呼び出すだけで使えるため、ゼロからプログラミングする必要がなくなり、ソフトウェアの開発を省力化できる。
公開されているWeb APIでは、「Facebook」「Twitter」「YouTube」「Googleマップ」などが有名で、スマートフォン向けのサービスやアプリ開発には欠かせない。
by 大塚商会 IT用語辞典
WebAPI特徴
- サーバで提供している(or されている)機能をhttpでネットワーク越しに使用する
- 決められたインターフェース、つまりパラメータやURL等で動作
- レスポンスは昔はXML、今はJSONが主流
- Webでajaxでよく利用される
- スマホアプリからの利用もあります
WebAPIの例
郵便番号検索API
郵便番号検索APIとは
郵便番号検索APIは、日本郵便が公開している郵便番号データを検索する機能をRESTで提供しています。
郵便番号検索API実行例 正常
{
"message": null,
"results": [
{
"address1": "広島県",
"address2": "広島市安佐南区",
"address3": "大塚西町",
"kana1": "ﾋﾛｼﾏｹﾝ",
"kana2": "ﾋﾛｼﾏｼｱｻﾐﾅﾐｸ",
"kana3": "ｵｵﾂﾞｶﾆｼﾏﾁ",
"prefcode": "34",
"zipcode": "7313174"
}
],
"status": 200
}
郵便番号検索API実行例 エラー
{
"message": "必須パラメータが指定されていません。",
"results": null,
"status": 400
}
{
"message": "パラメータ「郵便番号」の桁数が不正です。",
"results": null,
"status": 400
}
HTTP Status Code
400 入力パラメータエラー by 郵便番号検索API
一般的にWebAPIではHTTP Status Codeを返却
200：成功
400：リクエストが不正
404：Not Found
500：サーバエラー
HTTP Status Code
100番台 情報
200番台 成功
300番台 リダイレクト
400番台 クライアント起因エラー(未入力等)
500番台 サーバ側エラー
先輩に学ぶ HTTP Status Code
https://gist.github.com/rosylilly/3401612
HTTPメソッドについて
GET
リソースの取得
POST
リソースの新規登録
PUT
既存リソースの更新
DELETE
リソースの削除
RESTとは
REpresentational State Transferの略で、分散型システムにおける複数のソフトウェアを連携させるのに適した設計原則の集合、考え方のこと。Roy Fieldingが2000年に提唱した。
RESTの原則
主に以下の4つの原則から成る。
- アドレス可能性(Addressability)
提供する情報がURIを通して表現できること。全ての情報はURIで表現される一意なアドレスを持っていること。 - ステートレス性(Stateless)
HTTPをベースにしたステートレスなクライアント/サーバプロトコルであること。セッション等の状態管理はせず、やり取りされる情報はそれ自体で完結して解釈できること。 - 接続性(Connectability)
情報の内部に、別の情報や(その情報の別の)状態へのリンクを含めることができること。 - 統一インターフェース(Uniform Interface)
情報の操作(取得、作成、更新、削除)は全てHTTPメソッド(GET、POST、PUT、DELETE)を利用すること。
Swagger Editor
https://editor.swagger.io/
WebAPIの定義を作成可能なオンラインエディタ
swagger: "2.0"
info:
version: "1.0.0"
title: "Sample"
basePath: "/v2"
tags:
- name: "user"
description: "Operations about user"
schemes:
- "https"
- "http"
paths:
/user:
post:
tags:
- "user"
summary: "作成 user"
description: "This can only be done by the logged in user."
operationId: "createUser"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Created user object"
required: true
schema:
$ref: "#/definitions/User"
responses:
default:
description: "successful operation"
自動生成Interface
/**
* UserApiInterface Interface Doc Comment
*/
interface UserApiInterface{
public function createUser(User $body, &$responseCode, array &$responseHeaders);
public function deleteUser($username, &$responseCode, array &$responseHeaders);
public function getUserByName($username, &$responseCode, array &$responseHeaders);
public function updateUser($username, User $body, &$responseCode, array &$responseHeaders);
}
SwaggerとAmazon API Gateway
API GatewayからSwagger定義をインポート、エクスポート可能
Export as Swagger + API Gateway Extentions
swaggerの定義ファイル＋API Gateway独自の認証等の各種設定
AWS Amazon API Gateway
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/welcome.html
Amazon API Gateway は、規模に関係なく、独自の REST および WebSocket API を作成、公開、保守、モニタリング、保護できる AWS のサービスです。AWS または他のウェブサービス、AWS クラウドに保存されているデータにアクセスする、堅牢かつ安全でスケーラブルな API を作成できます。独自のクライアントアプリケーション (アプリ) で使用するための API を作成できます。または、API をサードパーティーのアプリ開発者に対して使用可能にできます。
by AWS ドキュメント » Amazon API Gateway » 開発者ガイド » Amazon API Gateway とは
API Gatewayからのエクスポート
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-export-api.html
API Gateway コンソールを使用した REST API のエクスポート
実習
参考文献など
Web API: The Good Parts 大型本 – 2014/11/21
水野 貴明 (著)
https://www.amazon.co.jp/Web-API-Parts-%E6%B0%B4%E9%87%8E-%E8%B2%B4%E6%98%8E/dp/4873116864