メインコンテンツへスキップ

3. API定義の作成

  • 更新

API定義の用意

API定義は、ソフトウェアやアプリケーションが他のソフトウェアと連携するために使用するAPIの詳細情報を提供する文書です。API利用者（開発者）がAPIの使用を理解するインタフェースとして用意するのが一般的です。

API定義の必要性

  1. 開発者コミュニケーション

    別のソフトウェアを統合する際、開発者はAPIを理解し、正しく使用する必要があります。API定義は、開発者間のコミュニケーションを円滑にし、協力を容易にします。

  2. エラーレポート

    API定義は、エラーや問題のトラブルシューティングに役立ちます。正確なエラーコードやメッセージが提供されれば、問題の迅速な解決が可能です。

  3. 適切な使用

    API定義にはAPIの適切な使用方法や制約事項が記載されています。これにより、開発者はAPIを効果的かつ安全に利用できます。

  4. バージョン管理

    APIが進化する場合、古いバージョンと新しいバージョンの間で互換性が保たれるようにAPI定義は重要です。開発者はドキュメントを通じてバージョン間の違いを理解できます。

  5. セキュリティ

    API定義にはセキュリティ要件と認証方法が含まれることがあります。これにより、アクセスを制御し、悪用を防ぐためのセキュリティ措置が実施されます。

  6. エコシステム拡大

    API定義は、外部開発者やパートナーと連携し、エコシステムを拡大する際に重要です。外部開発者がAPIを使用してアプリケーションやサービスを構築できるようにするための情報源となります。

API定義は、開発者コミュニティ、ビジネスパートナー、およびユーザーにとって、ソフトウェアプロジェクトの成功に不可欠な資産です。適切なAPIドキュメントを提供することは、効率的な開発、適切な利用、セキュリティの確保、およびビジネスの成長に寄与します。

OpenAPIとは

OpenAPI（Open Application Programming Interface）は、API（Application Programming Interface）を記述、ドキュメント化、および理解しやすくするための規格の1つです。OpenAPIは、APIの設計、開発、および管理を簡素化し、異なるソフトウェアアプリケーションやサービス間での効果的なコミュニケーションを支援します。

OpenAPIのファイル形式は通常YAMLまたはJSONで、これらのフォーマットを使用してAPIの仕様を定義します。この仕様は、SwaggerやOpenAPI Generatorなどのツールを使用して処理できます。APIの設計からドキュメント作成、実装、テスト、セキュリティ管理まで、OpenAPIはAPIライフサイクル全体にわたる役立つツールです。

Stoplight Studioを利用してAPI定義を作成する

API定義を作成するためのツールはいくつか存在します。

Stoplight Studioを利用してAPI定義を作成するフローをご紹介します。

1. ワークスペースの作成

以下からワークスペースを作成します。手順を進めて作成完了まで行ってください。

https://stoplight.io/welcome

stoplight.io_welcome.png

2. お使いのOSにあったソフトウェアをダウンロードします。

https://github.com/stoplightio/studio/releases

github.com_stoplightio_studio_releases.png

3. ソフトウェアを起動し、ワークスペースにログインしたらAPI定義の作成が可能となります。

今回作成したAPIのAPI定義は以下になります。

openapi: 3.1.0
x-stoplight:
  id: bjvald6rgfu6r
info:
  title: pointcloud
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /pointcloud:
    post:
      summary: Create New Pointcloud
      operationId: post-pointcloud
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    x-stoplight:
                      id: huqr1v3rq5cjx
              examples:
                New User Bob Fellow:
                  value:
                    id: 12
                    firstName: Bob
                    lastName: Fellow
                    email: bob.fellow@gmail.com
                    dateOfBirth: '1996-08-24'
                    emailVerified: false
                    createDate: '2020-11-18'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                download_url:
                  type: string
                  x-stoplight:
                    id: 9ct27l55ii345
                file_name:
                  type: string
                  x-stoplight:
                    id: wgoim2oqrwoi6
                command:
                  type: string
                  x-stoplight:
                    id: orhwlz70mv28r
              required:
                - download_url
                - file_name
                - command
            examples: {}
        description: ''
      description: Create a new pointcloud.
    parameters: []
  '/pointcloud/tasks/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get Pointcloud Task Info by ID
      tags: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    x-stoplight:
                      id: 2c42wnn9iu7uo
                  accepted_at:
                    type: string
                    x-stoplight:
                      id: 49kq0jzaw0c8y
                  status:
                    type: string
                    x-stoplight:
                      id: 9gp3au44u48gz
                  started_at:
                    type: string
                    x-stoplight:
                      id: by7nvf6kbatgs
                  finished_at:
                    type: string
                    x-stoplight:
                      id: 6y98h93nivdqa
                  result:
                    type: object
                    x-stoplight:
                      id: pd23wb6px7rx2
                    properties:
                      result_id:
                        type: string
                        x-stoplight:
                          id: hjb4txeow2m84
      operationId: get-pointcloud-task
      description: Retrieve the information of the task.
      requestBody:
        content: {}
  '/pointcloud/results/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get Pointcloud Result Info by ID
      tags: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    x-stoplight:
                      id: kkcnd8yif3ggm
                  download_url:
                    type: string
                    x-stoplight:
                      id: 1v4bmkqmgk9ub
      operationId: get-pointcloud-result
      description: Retrieve the information of the result.
components:
  schemas: {}

関連記事