僕が考えた最強のAPIドキュメント生成 - 銀の人のメモ帳
2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
Web APIにはJSONベースのフォーマットを使おう - Qiita
{ "response": { "id": 3342124, "message": "Hi!", "user": { "id": 3456, "name": "Taro Yamada", "image_url": "/images/taro.png" } } } など、どの構造がいいでしょうか？ もっと違う構造も考えられます。 JSONはシンプルですが、構造に制約がなさすぎます。適切な設計を行うには適切な制約が必要です。 そこで、plain JSONに少し制約を加えたJSONベースのフォーマットを使うことをおすすめします。 もしあなたが、JSONレスポンスをどのようなフォーマットにするかをチームで議論したことがあるなら、JSON APIは『自転車置き場の議論』に対抗する武器となる。 共有された規約に従うことで、生産性が向上し、汎用的なツールを利用でき、アプリケーションという重要なものに集中
全てがJSONになる - ✘╹◡╹✘
TL;DR JSON Schemaを使ってこういうことが実現可能になった。 ダミーAPIサーバの提供 ドキュメントの自動生成 APIクライアントの動的定義 APIサーバのバリデータの動的定義 APIサーバのレスポンスの自動テスト JSON Schemaとは JSON SchemaというのはあるJSONのデータ構造を記述するための方法および書式の仕様で、 JSON SchemaもJSONで記述される。 これを利用すれば、リソースベースの(=RESTfulライクな)APIの仕様が簡便に記述できる。 例えば、我々のAPIはレシピとユーザというリソースを扱っていて、 それぞれCRUDのAPIを備えており、レシピはidとtitleとdescriptionという属性を持つ、 という旨をJSON Schemaで表現できる。 なんで最近ちょっと流行ってんの Mobile First、 Service Or
ql.io
A declarative, data-retrieval and aggregation gateway for quickly consuming HTTP APIs Try me prodid = select ProductID[0].Value from eBay.FindProducts where QueryKeywords = 'macbook pro'; details = select * from eBay.ProductDetails where ProductID in ('{prodid}') and ProductType = 'Reference'; reviews = select * from eBay.ProductReviews where ProductID in ('{prodid}') and ProductType = 'Reference'
SQLとJSONをNode.js上で組み合わせた新言語「ql.io」をeBayが公開
eBayが、JavaScriptアプリケーションからSQL文のような形式でデータベースへの問い合わせを記述できるDSL（ドメイン固有言語）のql.ioを発表。オープンソースとして公開しました。 現在、多くのWebアプリケーションが、バックエンドとのデータのやりとりにHTTPをベースにしたAPIを用いています。しかし、WebベースのAPIによってデータを取り出すのは、プログラマにとって実は手間のかかることです。 例えば、キーワードを入力すると関連する商品の名前、詳細、購入者の評価をユーザーに表示する、というWebアプリケーションでは、まずキーワードでデータベースを検索して商品IDを取得し、今度はその商品IDをキーにして名前や概要、評価の情報を取得する、といったように、APIを繰り返し呼び出す必要があります。 ql.ioはこうした内容をSQLのように分かりやすい記述で実現するだけでなく、複数の
jqコマンドが実は高性能すぎてビビッた話
GWが始まりましたが、鎌倉のGWは観光客多すぎて逆に住民はげんなりして外に出なくなる感じです。とはいえ路地まで観光客が攻め込んでくることは少ないので、路地を散歩する分には天気がよくていい感じですね。ちなみに人力車のおにーさんはそういう味のある路地を知り尽くしているので人力車で移動するのはそこそこオススメです(ぼくは乗ったことないけど「こんなところも通るんだ!」ってところで見かけたりします)。 さて、jqというコマンドをご存じでしょうか。 jq jq is a lightweight and flexible command-line JSON processor. と書いてあるとおり、コマンドラインでJSONを扱うことができるコマンドです。で、今まさに仕事で巨大JSONと戦うことが多く、このコマンドが大活躍です。 とはいえ、ぼくの使い方としては「巨大JSONをキレイに整形して表示する」とい
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - ql-io/ql.io: A node.js based declarative, data-retrieval and aggregation gateway for quickly consuming HTTP APIs