はじめに

限られた時間の中で今後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使用例

test.cpp

#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の定義を作成可能なオンラインエディタ

sample.yaml　抜粋

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.php　抜粋

/**
 * 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