最近のウェブ開発では各機能ごとをAPIでつなぎ込む時代になっています。 そのため、各チームが開発をしていく上で、 他のチームにAPIの仕様を伝える方法をきちんとまとめておく必要が出てきています。 そんな中でAPIドキュメントにどのような役割が求められていて どのような選択肢があるか、一旦自分の把握している知識をまとめています。 (ここで書いているAPIは、httpでアクセスしたら、JSON形式でレスポンスを返すウェブサービスのAPIを指しています) APIドキュメントを用意する上で、すぐにぶつかる壁 APIドキュメントを用意する場合に、何も考えずにExcelやwikiにまとめると、早い段階で メンテナンスのコスト の問題にぶつかります。 『APIドキュメントを書く時間がない』 『本当にドキュメント通りの結果が返ってくるか、試してみないとわからない』 『実際に返ってくるAPIとレスポンスが違

Scalatra2.2リリース つい先日、Scalatra2.2のstable版がリリースされました。今回のバージョンアップではかなり大きな機能追加や変更がされたようで、私はまだまだ内容が把握しきれていません。こちらで変更点が確認できますので是非チェックしてみて下さい。 Swagger さて、本題です。SwaggerはREST APIのリファレンスを自動生成するためのフレームワークです。REST APIを提供するアプリケーションにおいて、Swaggerを利用してAPIの実装に必要な情報を追加すると、ブラウザで閲覧・実行が可能なリファレンスを生成することができます。 公式サンプル こちらにSwaggerで生成されたリファレンスのデモサイトが公開されています。下のスクリーンショットのような、とても見やすいリファレンスが生成されます。 各リソースをクリックすると、さらにビューが展開して以下のよう

デジタルビジネス時代を迎え、API連携へのニーズがこれまで以上に高まっている現在、API仕様を管理するOSSフレームワーク「Swagger」(スワッガー)が大きな注目を浴びています。本連載では、同フレームワークの未経験者・初心者を対象に、その概要や基本的な使い方を解説していきます。 仕様と実装の乖離が許されないAPI システム開発のトレンドとして、マイクロサービス化が進んできています。モノリス(一枚岩)スタイルの開発に比べて、アプリケーションの単位は小さくなり、多くのサービスが構築されます。 Uberの配車ビジネスやAirbnbの民泊に代表されるデジタルビジネスにおいても、APIエコノミー化が進んできており、Google Map APIやTwitter APIなどさまざまなAPIを組み合わせて素早くシステムを構築します。 Programmable Webでは、2017年1月時点で16,59

SwaggerのPHP実装であるSwagger-PHPの使い方についてLaravelプロジェクトで確認し、Swaggerとはどんなものか調査したメモになります。 Swaggerの全体像については、「RESTful APIの記述標準化を担うSwaggerとは？ | NTT Communications Developer Portal」が参考になりました。 Swaggerを利用したアプリケーション開発は、まずSwaggerドキュメントを作成して、サーバーのスタブとクライアントライブラリを生成し、APIロジックとクライアントUIなどを実装していくような流れになるといったところのようです。 Laravelはありませんが、コード生成ツール swagger-codegen には、Laravelの軽量版であるLumen用のサーバースタブは生成可能です。 この記事では、Laravel 5.2プロジェクト

Swaggerは、REST APIの仕様とそれに関連するツール群の総称です。REST APIの仕様を定義したJSONファイル(Swagger Spec)を軸に以下のようなツールから構成されています。 Swagger UI - Swagger Spec から動的にAPIドキュメントを生成するツール Swagger Editor - Swagger Specのエディタ Swagger Codegen - Swagger Specからクライアントのコードを生成するツール 最近では、Open API InitiativeがAPIの記述のためにSwaggerを採用して話題になりました。 www.publickey1.jp APIドキュメントのメンテは結構面倒 一般的にAPIの仕様書は、古くはExcel/Wordなどを使ったり、最近ではWikiやMarkdown形式で記述したりなどプロジェクトによって

2020-06-11 ZOZOMATのクロスプラットフォーム3D Android Objective-C Xcode iOS macOS 設計 C++ 3D ZOZOMATとは何でしょうか？オンラインで靴を購入する際に、サイズが合わないという問題を解決する仕組みです。1台のスマートフォンと紙製のZOZOMATだけで、正確に足のサイズを測れます。足をスキャンすると、高精度の3Dモデルが生成されます。最適なサイズの… ZOZOMATのクロスプラットフォーム3D 2020-06-11 近似最近傍探索Indexを作るワークフロー 機械学習 自動化 設計 マイクロサービス バックエンド インフラ Kubernetes Airflow はじめに こんにちは。ZOZO研究所のshikajiroです。主に研究所のバックエンド全般を担当しています。ZOZOでは2019年夏にAI技術を活用した「類似アイテム検

15. Swagger What is Swagger? The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a

背景 最近は変化し続ける要件に対応するために、システムも柔軟であることが求められています。 そのため、部分的に変更やスケールの可能なシステムを構築し、API経由で連携するマイクロサービス的アーキテクチャが増えてきています。 そういった設計の中で問題になっていくのが、従来のモノリシックなアプリケーションではIDEやコンパイラなどで行っていた、機能間のインターフェイスをどう管理するかという部分です。 Swaggerとは? SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークです。 公式サイトでは、The World's Most Popular Framework for APIsと謳っています。 その理由は、マイクロソフト、Google、IBM、SmartBearなどを大手の企業を含む「Open

WordPressが整備を進めているREST APIなら、WordPressで本格的なSPA（シングルページアプリケーション）が作れる？ REST APIとAngularJSを使って、WordPressの記事をすぐに編集できる投稿アプリを作ってみました。 本記事はJay Shields、Simon Codringtonが査読を担当しています。最高のコンテンツに仕上げるために尽力してくれたSitePointの査読担当者のみなさんに感謝します。 AutomatticとWordPressコミュニティがWordPress REST APIプラグインをWordPressの内部へ組み込む方向で動いています。つまり、プラグインを使わなくてもAPIが利用できるようになります。これからどんどんWordPressとフロントエンドのJavaScriptフレームワークとの統合を目にするようになるでしょう。 Wor

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 「翻訳: WebAPI 設計のベストプラクティス」を読んで色々と思うところがあったので書きました。 上記の記事は訳文でありますので、正しくは「Best Practices for Designing a Pragmatic RESTful API」に対する所感と述べた方が良いのかもしれませんが、日本語で通して読めるよう Qiita に投稿された訳文に対する所感として書いています。 以下では「翻訳: WebAPI 設計のベストプラクティス」並びに「Best Practices for Designing a Pragmatic RESTf

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? これは Enchant の開発者である Vinay Sahni さんが書いた記事「Best Practices for Designing a Pragmatic RESTful API」1を、ご本人の許可を得て翻訳したものです。 RESTful な WebAPI を設計しようとすると、細かなところで長考したり議論したりすると思います。また、他の API に倣ってやってはみたものの、本当にそれでいいのか、どうしてそうしているのか分からない、何てことも少なくはないと思います。 この記事では、そのようなハマリどころについて Vinay さん

Laravel 5.3 ではOAuth2プロバイダを提供するための公式パッケージLaravel/passportが登場しました。 このパッケージを使えば難しい設定なしにすぐにOAuth2プロバイダをアプリケーションに構築することが可能です。では、やってみましょう。 基本的な手順は公式ドキュメントにあるとおりです。(日本語版は現時点で未訳)→翻訳されました。 Laravel Passportのドキュメント、独自用語があるので、ソースを確認しながら翻訳。こりゃ時間がかかる。 #例の愚痴です — Hirohisa Kawase (@HiroKws) September 25, 2016 (お疲れ様です) 今回はアプリケーションの作成から追っていきます。 もちろんLaravel 5.3の動作要件であるPHP5.6.4+が必要です。 (手元では5.6.24/7.0.10でテストしています。) Win

概念としてとしてのRESTは、 Roy Fielding が博士論文「 Architectural Styles and the Design of Network-based Software Architectures 」で導入したものです。その16年後、アーキテクチャとしてのRESTは、APIを設計・構築するための最も広く受け入れられた方法となっています。RESTについては私たちはみんな聞いたことがありますし、自分たちが実際にRESTfulなAPIを構築しているとほぼ皆が思っています。しかし、それは本当でしょうか？ 「RESTとは何か？」ということを自分たちにもう一度思い出させたうえで、さらにRESTを補う別の方法、「HATEOAS」と呼ばれるものの話に続けていきましょう。 RESTとは何か？をもう一度 私はこれを説明するための良い方法について考えていたのですが、Ryan Tomak

API実装してますか？ 弊社では最近APIにLumen(PHP), Zend Expressive(PHP), echo(Go)が利用されています。 そのなかでも徐々にAPIを表題のHATEOASへとシフトしつつあります。 HATEOASに関しては下記を参照ください postd.cc そのHATEOASですが、Lumenを使って実装する簡単な例を紹介します。 記事を返却するAPI jsonで返却するAPIの実装をしてみましょう。 Article Entity <?php namespace App\Domain\Entity; /** * Class Article */ final class Article { /** @var int */ private $id; /** @var string */ private $title; /** @var Comment[] */ pr

前回の記事では、Laravelでフロントエンド開発を行うための開発環境の作り方を解説しました。今回は、LaravelでWeb APIを作る方法を解説します。 データベースの準備 アプリケーションのデータはデータベースに保存するようにしたいので、セットアップを行います。 Laravelアプリケーションを作成すると、以下の値でデフォルトの接続情報が作成されます。 データベース: MySQL データベース名: homestead ユーザ名: homestead パスワード: secret ローカル開発環境にMySQLがインストール済みなら、上と同じ条件で新しいデータベースを作成するのが手軽です。 手元の環境にMySQLをインストールしたくない、といった場合には、開発用VMのLaravel Homesteadを利用するのが良いでしょう。 DBへの接続情報は、アプリケーションのルートディレクトリの「