Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
1
Help us understand the problem. What is going on with this article?
@piyopiyo

WebAPI

More than 1 year has passed since last update.

WebAPI

by piyopiyo
1 / 19

はじめに

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

1
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
piyopiyo

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
1
Help us understand the problem. What is going on with this article?