2
Help us understand the problem. What are the problem?

More than 1 year has passed since last update.

posted at

updated at

Organization

API・REST・Swagger

(狭義の)APIとは

Application Programming Interfaceの頭文字をとっています。
概要としては、一つのソフトウェア(あるいはアプリケーション)と、また別のソフトウェア(アプリケーション)をつなげるための界面(Interface)です。
APIとしてソフトウェアに設けた公開窓口から、第三者が開発した別のソフトウェアとコミュニケーションを取り、様々な機能を共有することができます。

具体例として、APIを利用した認証機能があります。
以前は、認証が必要なコンテンツにログインするさい、異なるサイトやアプリごとにログイン情報を入力する必要がありました。しかしAPIを利用することで、そうした情報をいちいち入力しなくとも、SNSなど一つのアカウント情報を共有するだけで、異なる様々なプラットフォームにログインすることが可能になりました。

Web APIとは

APIには様々な形態がありますが、その一つに、Web上でAPIのやり取りを可能にしたWeb APIがあります。

Web APIでは、クライアントコンピューターのプログラムからWebサーバーに対して、HTTPプロトコルでリクエストを送信し、処理結果としてHTTPレスポンス(主にJSONやXMLの形式)が返却されます。レスポンスを受け取ったクライアントは、結果をブラウザで表示したり、CSV形式等に変換して使用することも可能です。

天気と服装、天気と栄養など、複数のAPIを組み合わせて新たな価値を生み出すマッシュアップが容易であることも、Web APIの人気の一因です。

RESTとは

REpresentational State Transferの略で、分散型システムにおいて、複数のソフトウェアを連携させるのに適した設計原則のことを指します。基盤となっているのは、下記の四項目です。

・セッションなどの状態管理を行わず、やり取りされる情報はその情報自体で完結して解釈することができる
=> WebにおけるHTTP自体には、セッション管理の機能はない
=> ステートレス(=state、状態/=less)であること

・情報を操作するさいの命令の体系が、あらかじめ定義・共有されていること
=> Webにおける情報の操作(取得、作成、更新、削除)は、すべてHTTPメソッド(GET、POST、PUT、DELETE)を通じて行われる
=> Uniform Interface(Uniform = 共通、統一)

・すべての情報が、汎用的な構文で一意に識別されること
=> 提供されるすべての情報が、URL/URIで表現される一意なアドレスを持つ
=> Addressability (Address(= 呼ぶ) + able(= 可能、できる) )

・情報の一部として、別の情報や(その情報の別の)状態へのリンクを含めることができること
=> HTMLやXMLの書式(ハイパーメディア的な書式)で情報を表現する
=> Connectability (Connect(= つながる) + able(= 可能、できる) )

RESTful APIとは

上記のRESTの考え方に則って設計されたAPIのこと。
狭義には、パラメータを指定して、特定のURL(エンドポイント)にHTTP(GET, POST, PUT, DELETE)でアクセスすることで、XMLやJSONなどで記述されたレスポンスが返却されるようなシステム、および、そのような呼び出し規約を指します。

Swaggerとは

APIインターフェース(APIの仕様書に該当する)を作成するための、オープンソースのフレームワークです。

名称 説明
Swagger Specification / Swagger Spec Swaggerの中心概念。Swaggerの書式に従って、APIインターフェイスを記述する仕様書(YAML/JSON)
Swagger Editor Swagger Specification作成・編集用のエディタ。Webブラウザ上で動的に作成できるため、リアルタイムで構文をチェックすることが可能。
Swagger Codegen Swagger Specificationの設計内容から、APIのクライアントライブラリやスタブコード等を自動生成してくれる
Swagger UI Swagger Specificationで記載された設計から、HTML形式でドキュメントを生成するためのツール

Swaggerの書き方

項目詳細などは =>>>>
https://swagger.io/specification/#versions
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema

swagger.yml
openapi: "3.0.2"

info: # APIに関するメタデータ。
  title: "Swagger Sample API" # API名称(必須)
  version: "1.0.1" # APIバージョン(必須)
  description: "サンプルです"

tags: # API管理用のタグ(エンドポイントのグルーピング等)。必須ではない。
- name: "get"
  description: "tag for get"
- name: "post"
  description: "tag for post"

servers: # APIが存在するサーバー情報(URL)
  - url: "https://development.big-server.com/v3" # サーバー情報(必須)
    description: "API サーバー"

paths: # APIのエンドポイント
  /{login_id}/sending:
    get: # HTTPメソッドに該当する箇所(Operation Object)
         # parameters(GET) / requestBody(POST) / responses等が含まれる
      tags:
      - "get"
      parameters:
        required:
        - in: "header" # パラメーターが含まれる位置(query/header/path/cookie等)
          name: "Authorization" # パラメーター名
          required: true # パラメーターが必須か否かObject(Components Object参照)
      responses:
        "200":
          description: "Successful!"
        "400":
          description: "Error"
          schema: 
            $ref: "#/components/schemas/ErrorModel" # Reference Object(該当URIにある共通データの利用)
    post:
      tags:
      - "post"
      parameters:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/JsonModel'

      responses:
        "200":
          description: "Super Successful!"
        "400":
          description: "Error"
          schema: 
            $ref: "#/components/schemas/ErrorModel"

components:  # 共通データをComponent Object以下に記載する
  schemas:  # 共通モデル(モデル同士を入れ子にすることも可)
    ErrorModel:
      type: "object"
      properties:
        data:
          type: "object"
          properties:
            error_message:
              type: "string"
              description: "Error Message"
            error_code:
              type: "string"
              description: "Error Code"
    JsonModel:
      description: "Json"
      type: object
      required:
        - login_id
      properties:
        login_id:
          type: string
          description: "ID for logging in"

# 下記項目で共通データを利用することも可能
# parameters: GETのパラメーター
# requestBodies: POSTのパラメーター(ボディ)
# responses: レスポンス(schemaを$refすることも可)

参考文献

以下の文献を参考にさせていただきました!ありがとうございました!
@NagaokaKenichi様
Restful APIについて
Restful APIについて(辞書)
APIについて
分散型システム
Swaggerについて
@gcyata様
Swagger IO
Swagger Git
Swagger書き方詳細

Register as a new user and use Qiita more conveniently

  1. You can follow users and tags
  2. you can stock useful information
  3. You can make editorial suggestions for articles
What you can do with signing up
2
Help us understand the problem. What are the problem?