翻訳: WebAPI 設計のベストプラクティス - Qiita
これは Enchant の開発者である Vinay Sahni さんが書いた記事「Best Practices for Designing a Pragmatic RESTful API」1を、ご本人の許可を得て翻訳したものです。 RESTful な WebAPI を設計しようとすると、細かなところで長考したり議論したりすると思います。また、他の API に倣ってやってはみたものの、本当にそれでいいのか、どうしてそうしているのか分からない、何てことも少なくはないと思います。 この記事では、そのようなハマリどころについて Vinay さんなりの答えを提示し、簡潔かつ明快に解説してくれています。 今後 WebAPI を設計される方は、是非参考にしてみてください。 なお、誤訳がありましたら編集リクエストを頂けると幸いです。 まえがき アプリケーションの開発が進むにつれて、その WebAPI を公
APIデザインにおける七つの大厄介 | POSTD
(編注：2016/7/29、頂いたフィードバックを元に記事を修正いたしました。) APIをデザインするということは、科学であり技術でもあります。多くの頭の良い人たちが失敗を重ねてきました。成功している人たちは、APIの主な目的を念頭においてデザインしているのです。その目的とは、「開発者たちをウンザリさせる」ということです。 親愛なる仲間たち、その崇高っぽい追求を称えるべく、「APIデザインにおける七つの大厄介」を共に数え上げようではありませんか（私がしたことを見てください）。 リスティクル（箇条書き形式の記事） を書くつもりはないのですが、少なくともタイトルは 教養ある宗教的文献が参照元 です。 まず、ルールを決めましょう。ここでは、成功し、きちんと機能しているAPIを取り上げます。ですから、「動かない」とか、「大量のセキュリティホールがある」といったことは厄介ごとに数えません。「致命的」
高い互換性と寿命の長いWebAPIをつくるには - トレタ開発者ブログ
Web APIの開発を担当しているswdyhです。 以前からWebサービスのサーバサイドの開発をしていたんですが、トレタに入るまでアプリのためのWeb APIの開発というのはしていませんでした。トレタに入って2年半くらいずっとアプリのためのAPIを開発していて、同じサーバサイドの開発でも、それまでとの開発とは違う点があり、悩ましくも面白く感じたのでまとめてみました。 サービスとアプリの話 トレタで提供しているサービスは、飲食店むけの予約管理サービスで、電話などで予約を受け付けたときに、iPadのアプリを操作して予約を入力してもらい、実際にお客さんが来店したときにはiPadを見て案内するというふうに使ってもらうものです。他にもいろんな機能やこだわりポイントがあるサービスなんですが、そのへんはWebサイトを見てみてください。 トレタのアプリはiPadのネイティブアプリで、ほぼ全てのデータをサー
swaggerでAPIドキュメントを書いたらめっちゃはかどった話 - kaz29
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形式で記述したりなどプロジェクトによって
僕が考えた最強の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を使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
AWS の API を利用するときに気をつけたい 3 つのポイント | はったりエンジニアの備忘録
AWS の魅力は API を使ってインフラをコントロールできる点です。インフラだけでなく SQS や DynamoDB といったサービスも API で操作します。ほぼすべてのサービスに API が用意されているので、AWS を使いこなせば使いこなすほど API の利用頻度も上がります。 今回は AWS の API を利用するときに気をつけたいポイントをまとめてみました。 リトライ処理を入れる AWS に限ったことではありませんが、API リクエストはさまざまな理由で一時的に失敗する可能性があります。クライアント側のネットワークエラーの可能性もありますし、大量のリクエストを送ってサーバ側でスロットリングされているかもしれません。 なので、API リクエストは 一時的な失敗を前提 にリトライ処理を入れましょう（AWS SDK を利用しているのであればリトライ処理は自動的に行われます）。一度失敗
VISAがオンライン決済用RESTful APIを一般公開！ - 熟れたC++使いが社会問題と趣味をつぶやく
www.programmableweb.com しばらくオンライン決済系の動向を見ていなかったので、このニュースを見た時には結構驚きました。 これまではPayPalや他のサービスがオンライン決済APIの代名詞のようなものだったのですが、とうとうVISAのようなメジャーが直接公開する運びとなったのですねぇ・・・。 昔はオンライン決済を一般人がやろうと思うと結構ハードルが高いもので、銀行等の金融機関だけのもの、という感じでした。それがPayPal等の登場によりかなり簡単に扱える様になりました。しかしPayPalの問題は、決済を行いたいお客さんが一度PayPalに個人情報やカード情報を入力しなければならないという点でした。つまり、PayPalアカウントを一度作るというちょっとした障壁が残っていたのです。VISA APIによりおそらくこの障壁がなくなると思われるので、この点は大きいのではないでしょ
Goベースのマイクロサービスフレームワーク"goa"によるサービスAPIの定義，レビュー，実装
RightScaleのシニアシステムアーキテクトであるRaphael Simon氏が，GoベースのHTTPマイクロサービスフレームワーク“goa”を開発した。DSL(Domain-Specific Language)によるサービスAPIの定義と，対応するサーバとクライアントの“ボイラプレート”コード，およびドキュメントの自動生成が可能だ。 goaを紹介するGopher Academyのブログ記事には，RightScaleのエンジニアリングチームが実施中の，モノシリックRuby on RailsアプリケーションからGo(言語)ベースのマイクロサービスアプリケーションセットへの移行作業について述べられている。このマイグレーションで大きな課題となっているのが，設計の行き届いたサービスAPIの作成だ。そのためにマイクロサービスAPIの設計とレビュー，実装をサポートするツール群が開発された。この作業
APIへのPUTやDELETEもブラウザから試す - 貳佰伍拾陸夜日記
APIサーバを作っているととにかくcurlで叩いてレスポンスを| jq .して見て, とやっていてリクエストボディのJSONの中括弧や引用符の対応がとれてなくてイライラしたり, 必要なヘッダをつけ忘れていてハマったり, とにかく非効率な感じがしてきたので, ブラウザ上から操作できるようにして, リクエスト内容の編集も(コマンドラインよりは)簡単にできるようにしてみた. 特徴 スタンドアロンなサーバとして動くのでどんなAPIサーバに対しても使える API叩く先のホストをコマンドライン引数で指定するとそこへリバースプロキシする 結果のJSONを自動整形・ハイライトする そういうのやってくれる拡張入れてるときは余計なことはしないで拡張に任せる リクエスト内容のエクスポートが可能 パーマリンク curlコマンド HTTPプロトコル インストール golang環境を用意する 以下のコマンドを実行 $
Web API設計指針を考えた｜デロイト トーマツ ウェブサービス株式会社（DWS）公式ブログ
小文字のみを使用する。 単語をつなげる必要がある場合はダッシュを利用する。 単数形よりも複数形をつかう。なお、実装がRailsの場合でテーブルの複数形が誤っている場合には、URLは正しい複数形としてRails側を修正する。（APIに実装を反映させるべきではない。） スペルミスをしない。 URLの階層は浅く保ち、複雑さはクエリパラメーターに押しこむ。 クエリパラメータ名は配列で複数渡すものについては複数形、一つだけ渡すものについては単数形とする。 ページングにはper_page、pageというパラメータ名を使用する。 と書いてきたが、ただし、RESTには必ずしもこだわらず、あくまで利用側の利便性を重要視した設計とする。 1つの作業を完結するために複数回のアクセスを必要とするようなAPIの設計はChatty APIと呼ばれる。これはネットワークのトラフィックを増加させ、クライアントの処理の手間
『Web API: The Good Parts』 を読んだ - ひだまりソケットは壊れない
Web API: The Good Parts 作者: 水野貴明出版社/メーカー: オライリージャパン発売日: 2014/11/21メディア: 大型本この商品を含むブログ (6件) を見る 同僚から借りて読みました。 全体としては Web API の設計に少しでも携わる人間ならとりあえず読んでおいたらいいんじゃないかなーという感じです。 薄いし。 本書を読んだからと言って最高の Web API の設計ができるようになるとは思わないですが、Web API の設計をする際に知っておくべきことが一通りまとまっていて良い感じだと思いました。 学びメモ 知らなかったことや、なんとなく知ってたけど改めて調べたことなどまとめておきます。 RFC 5861 での Cache-Control ヘッダの拡張 RFC 5861 にて、Cache-Control ヘッダの 2 つの拡張が定義されています。 sta
http api design
以下なドキュメントを発見しておりまして。 HTTP API Design Guide なんとなくメモをとってみました。 Contents として以下が列挙されています。 適切なステイタスコードを戻しなさい 戻すことができる全てのリソースを戻しなさい リクエストボディに含まれるシリアライズされた JSON を受け付けなさい ID じゃなくて UUID 使った方が良いですよ 標準的なタイムスタンプを使いましょう UTC 時刻は ISO8601 フォーマットで使いましょう 一貫性のあるパスフォーマットを使いましょう 小文字とダッシュを使いましょう 外部キーのリレーションは入れ子に 利便性をはかるため non-id dereferencing をサポートしなさい エラーの場合のレスポンスボディについて ETag ヘッダを含めなさい Request-Id ヘッダを API レスポンスに含めなさい P
WebAPIでエラーをどう表現すべき？15のサービスを調査してみた - Qiita
2017-01-05 追記 2016年3月にエラーの標準形式RFC7807「Problem Details for HTTP APIs」が提案され、今日現在proposed standard(標準化への提唱)となっています。こちらも是非ご覧ください。 RFC 7807 - Problem Details for HTTP APIs HTTP APIの詳細なエラー情報をレスポンスに持たせるための仕様 最近はREST APIを提供しているサービスが増えてきていますね！また公開されるAPIだけでなく、Microservicesなアーキテクチャを採用して、バックエンドがWeb APIで通信するケースも増えてきているように思います。 APIを使うときはあまり気にしたこともなかったですが、いざAPIを設計してみるとどんなインターフェイスがいいのか、どんな形式がいいのかといった疑問が次々と出てきます。
習うより慣れろ。WP API にリクエストをいっぱい投げる。& REST クライアント “Paw” が超便利。 - Shinichi Nishikawa's
ホームWordPresswp-api習うより慣れろ。WP API にリクエストをいっぱい投げる。& REST クライアント “Paw” が超便利。 WP REST API サイトの主要なページをじっくり読んだところで、次は習うより慣れろということで、リクエストいっぱいしてみて、レスポンスをじっくり見てみよう、という趣向で進めてみたいと思います。 前提として、以下の記事を読んでおくと、話がよく分かると思います。 http リクエストをターミナルからお試しする httpie WP REST API のドキュメント内の用語集を簡単に翻訳する WP REST API ドキュメント Discovery また作業にあたり、Mさんこと @miya0001 さんから Paw – The ultimate REST client for Mac という、REST クライアントを紹介してもらいましたので使って
認証を含む API 開発で検討すべきこと - ボクココ
ども、@kimihomです。 API に関する基礎的な話で、なぜ API が重要なのか、APIの実装で注意する点について記述した。 今回はAPI開発において最も頭を悩ます、認証の問題について考えてみたい。 API における認証 よくあるログインが必要なページを考えてみていただきたい。 通常のWebアプリケーションであれば、Cookieという仕組みを使って毎回Webサーバーにアクセスするときにsession idというものを送信し、それとユーザー情報を紐付けたデータを取ってくることで、どんなユーザーからリクエストが来たのかをWebアプリケーション側で判断することができる。これにより、私たちはいつも閲覧しているWebアプリケーションが自分専用の画面として見れるようになっている。 これがAPIになると話は違ってくる。Cookieという仕組みが使えないのである。ということで、なんとかしてAPIにア
Slackに気を取られすぎる問題とその解決 - 無理しない感じ
この記事は「さくらインターネット Advent Calendar 2015」の20日目の記事です。 Slackは非常に気の利いたチャットツールで、とても便利に使っています。 問題 しかし、このツールにも問題があります。 ジョインしているチャンネルが多くなると未読のメッセージがつぎつぎに溜まり、未読を消化したい欲と仕事に集中したい欲を常に戦わせる状態となります。 （そして、だいたい未読を消化したい欲が勝ちます） 解決 仕事の効率を高めるはずのツールで仕事の集中力を欠いてしまっては仕方がないので、この問題を2つのツールを使って解消します。 Slack Silencer github.com まず、Slack Silencerというツールを使います。 このツールは指定したチャンネルをミュートにしてくれます。ミュート状態のチャンネルはリスト上に薄く表示され、メッセージの未読を伝える白文字の表示にな
外部APIを使うController用のTest Doubleライブラリを書いた - Qiita
Goで net/http を使ったControllerのテストには、 net/http/httptest モジュールを使うと擬似的にサーバをその場で立て、登録したハンドラにリクエストを送れます。 ただ、APIに使うアクションはたびたび、外部のAPIを叩くこともあります。 その際、テストを実行するときに外部APIを使えない状況(本番環境とは違う状況、例えば、production用のAPIの発行には金銭が発生するなど)に遭遇します。 そんなときに知られているテクニックとして、テスト時に外部APIへのリクエストをDouble(Stub)することです。 その外部APIが返却するであろう期待値を登録しておけば正常ケースを、エラー値を登録しておけばエラーケースをテストできます。 ここで例に挙げるStubする方法は、 http.Client をもとにHTTPリクエストすることを前提としています。 ではど
DSLでAPIを書きたい!!APISchemaでらくらくAPI生活をはじめよう - hitode909の日記
この記事は，はてなエンジニアアドベントカレンダー2015の5日目です． 前日はこの記事でした．スクリーンショットで振り返る・はてなブログ記事編集画面デザインの歴史 - Hatena Developer Blog 最近作った(といっても去年から作っている…)，APISchemaというライブラリをご紹介します． APISchemaとは BMIを計算しよう スキーマを書こう メタデータ リソースの定義 エンドポイントの定義 スキーマを使う スキーマのパース ルーターを生成して，ルーティングをおこなう リクエストのバリデーションをおこなう レスポンスのバリデーションをおこなう APIのドキュメントを配信する 採用実績 関連 JSON Schema 便利グッズ まとめ APISchemaとは APISchemaは，DSLでHTTP APIの定義を書けるものです．以下のような機能を持っています． AP
RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに
RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに 10年以上前、XMLの登場に続いてXMLベースのAPIを記述する標準フォーマット「WSDL」が提唱されました。 WSDLにはAPIの仕様がマシンリーダブルな形で記述されており、APIを呼び出すためのプロトコルやデータフォーマットをあらかじめ知ることができます。WSDLを利用することで、APIをコールするためのコードを自動生成することが可能でした。 しかしXMLベースのAPIは期待されたほど普及せず、現在ではよりシンプルなRESTful APIが事実上の標準となっています。 そしてRESTful APIのためのWSDLとも言うべき、RESTful APIのインターフェイスを記述するための標準フォーマットを推進する団体「Open AP
Springfox+Swagger+Bootprintによる即席REST API仕様書作成 - Taste of Tech Topics
こんにちは。阪本です。 世の中、Swaggerが注目を浴びてきていますね。 開発のスピードアップが求められる中、「外部IF仕様書なんて書いてられねぇ！！」なんて言って実装をバリバリ進めてしまいそうですが（アカンアカン）、そうは言っても外部IF、他社との仕様調整も必要。 そんなときに有効な、実装しながら仕様書も作れるSpringfox+Swaggerに加え、ドキュメント生成ツールのBootprintを使って、簡易的な仕様書を作ってみました。 仕様書の動的生成 以下のようなシンプルなSpringBootアプリケーションから、REST APIを生成してみます。 @SpringBootApplication public class SwaggerExampleMain { public static void main(String[] args) { SpringApplication.run
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
