RESTful のウェブ API 設計で避けるべき 6 つのよくあるミス | Google Cloud 公式ブログ
※この投稿は米国時間 2022 年 12 月 1 日に、Google Cloud blog に投稿されたものの抄訳です。 オンラインで、組み立て式のテーブルを注文したとします。ところが、パッケージを開けてみると、組立説明書が入っていません。完成品がどんなものかはわかっていても、それぞれのパーツをどう組み立てればいいのか、まるでわかりません。設計が不十分な API を使うコンシューマ開発者も、同じような経験をしているといえます。適切に設計された API なら、容易に見つけ、検索してアクセスし、使用することができます。高品質の API は、コンシューマ開発者がアイデアをひらめき、新しいユースケースを作り上げる手助けになってさえくれます。 もちろん、API 設計を改善する方法はあります。たとえば、RESTful のプラクティスに従うなどです。しかし、お客様が知らず知らずのうちに、ちょっとした不便
OpenAPIを使ってAPIドキュメントとモックサーバーを良い感じにした話
2021年6月2日に行われたSendai Frontend Meetup #6で使用したスライドです。 GitHub サンプルコード https://github.com/KanDai/openapi-sample ReDocで生成されたドキュメント https://kandai.github.io/openapi-sample/ About Swagger Specification https://swagger.io/docs/specification/about/ Swagger Editor https://editor.swagger.io/ Stoplight Studio https://stoplight.io/api-design/ Swagger UI https://petstore.swagger.io/ Redoc https://github.com/Red
AmazonのAPI設計方針 (The Bezos Mandate) - Qiita
はじめに The Bezos Mandateという文書があります。日本語に訳すと「ベゾスのお達し」とか「ベゾスの勅令」でしょうか。 言わずと知れたAmazon.comのCEO、ジェフ・ベゾスが開発チームに通達した内容です。 これが（元Amazon.com従業員によって）公開されたのは2011年ですが、ベゾスがこのお達しを出したのは2002年前後です。17年経過した現在でも真理をついているどころかようやく時代がベゾスに追いついたかという感想です。 この記事ではThe Bezos Mandateの紹介と、僭越ながら補足説明も行います。 お達しの内容 原文は元Amazon.com従業員のGoogleエンジニア（公開当時）、Steve Yeggeによって公開されました。 Google+にStevey's Google Platforms Rantというタイトルで、Amazon.comと比べたGoo
TypeScript の型生成における OpenAPI Generator のハマりどころ - READYFOR Tech Blog
こんにちは。READYFOR でフロントエンドエンジニアとして働いている菅原（@kotarella1110）です！ 嬉しいことに、READYFOR のプロダクト開発組織は急拡大中で、正社員の人数は 2019年7月時点では8名でしたが2021年4月現在は29名になりました 🎉 その反面、組織が大きくなってくると「我々はどこに向かってるんだっけ？」「あの人、最近はどんなことに取り組んでいるんだろう？」といった「見えないこと」が増えてきます🤔 この「見えないこと」を減らすために、READYFOR では毎月「プロダクト開発本部会」を開催しています。 プロダクト開発本部会では、必要な全体周知（組織やプロダクトの方針等）や月替わりプレゼンテーションを行っています。 本記事はこのプロダクト開発本部会の月替わりプレゼンテーションで発表した内容になります。 はじめに 以前 READYFOR で初主催とな
熱心な REST 信者、が 挑んだ AppSync/GraphQL API 開発 | Slides | Riotz.works
「Serverless Meetup Japan Virtual #14」にて発表した際のスライドです。
APIに利用制限をかけるとしたらどういうやりかたがあるのか - おもしろwebサービス開発日記
この記事はSmartHR Advent Calendar 2020 11日目の記事です。 僕のお手伝いしているSmartHRでは、毎週バックエンドエンジニアが集まり、技術的なトピックについて共有、相談しあうミーティングを開催しています。そのミーティングでは僕がTipsなどを共有するコーナーが常設されています*1。 このエントリでは、そのコーナーで共有した内容をひとつ紹介します。 APIに制限をかける方法について APIを外部に提供するとき、一定の制限をかけてユーザがAPIを乱用するのを防ぐことはよくあることではないでしょうか。素直に考えると「1時間に5000回までAPIを実行できる」のようなやり方を思いつきますね。GitHubのAPIもそのやり方ですし、SmartHRのAPIも同様です。 じゃあそれでいいのでは。となるかもしれませんが少し待ってください。いろんなクライアントがAPIを大量に
5歳娘「パパ、変なAPIを作らないで？」 - Qiita
とある休日 娘（5歳）「パパ、一緒に技術ブログを始めない？」 娘「昔から私とパパがローカルに書き溜めてる技術記事が、かなり溜まってきたでしょ？」 娘「それをブログとして公開してみようよ」 ワイ「おお、それは楽しそうやな」 ワイ「どこのブログサービスを使おうかいな」 娘「せっかくなら、ブログシステムから自分たちで作ってみようよ」 娘「私はフロントエンドを担当するから」 娘「パパはRuby on Railsか何かで、APIを作ってよ」 ワイ「おお、Ruby on Railsなら昔やったことあるわ」 ワイ「RailsのAPIモードで、ブログ記事を返すエンドポイントを作ればええんやな」 娘「そうそう」 次の日 ワイ「API、できたで！」 ワイ「/api/articlesっていうエンドポイントにアクセスしてくれたら」 ワイ「ブログ記事が取得できるようにしておいたわ」 娘「さすがパパ」 娘「そういえば
HTTPリクエストを型安全にする手法とOSS - Qiita
気付いた頃には全部埋まってた本命のTypeScriptアドベントカレンダーの初日が投稿されないようなので代わりに投稿させてもらうことにしました！ エンドポイントに文字列を使い続ける限りHTTPリクエストは型安全に出来ない axios, ky, fetch, request, superagent... どれを使っても「エンドポイントの指定が文字列」なせいで型安全にならない・・・ という課題にTypeScriptユーザーなら誰もが共感してくれるのではないかなーと思ってます (TypeScript 4.1 の template string types である程度は改善しそうです) 例えば、axiosで以下のようなリクエストをするとして、 const userId = 1 const res = await axios.get<History>(`/user/${userId}/histori
モックAPIサーバーにPrismが良かったので使ってみた - Qiita
Prismとは Prism (https://stoplight.io/open-source/prism/) は、OpenAPIの記述に基づいてランダムなダミーレスポンスを返してくれるAPIモックツールです。 何が良いのか？ 設計通り のレスポンスが、自動で生成されて返却される これは圧倒的なアドバンテージではないでしょうか？ もし自力でAPIのモックを用意しようとする場合、フロントエンド単体で完結させようとしたら以下のようになると思います。 APIの仕様書を見てレスポンスのスキーマを確認し スキーマに基づいてそれっぽいダミーデータをチマチマと書いて アプリケーション内にレスポンスを返す用のjsonファイルを作ったりして ダミーデータを使う時とそうでない時で、HTTP通信部分のソースを書き換えて 実際にダミーを取ってきてみたらスキーマ通りでないものだったからダミーデータを作り直して 動く
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を設計してみるとどんなインターフェイスがいいのか、どんな形式がいいのかといった疑問が次々と出てきます。
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は『自転車置き場の議論』に対抗する武器となる。 共有された規約に従うことで、生産性が向上し、汎用的なツールを利用でき、アプリケーションという重要なものに集中
RESTful API設計におけるHTTPステータスコードの指針 - Qiita
RESTful APIを設計した際のステータスコードの指針です。 メソッド別 GET 成功した場合 200 OK：最も一般的 304 Not Modified：条件付きGETでキャッシュを使わせたい場合 POST 成功した場合 201 Created 作成したリソースのURIを示すLocationヘッダを付けておく 議論 200 OKだとまずいのか？ 200 OKを応答する実装も多くあり、まずいというわけでもない 200 OKはPOST結果がキャッシュ可能、201 CreatedはPOST結果がキャッシュ不可能として分けてもいいが、そこまでする必要があるか？（POSTのキャッシュは一般的ではない） 204 No Contentだとまずいのか？ クライアントがPOST結果を事前に全て知っているわけではないのでNo Contentは不親切では？ 失敗した場合 409 Conflict：作成しよ
翻訳: WebAPI 設計のベストプラクティス - Qiita
これは Enchant の開発者である Vinay Sahni さんが書いた記事「Best Practices for Designing a Pragmatic RESTful API」1を、ご本人の許可を得て翻訳したものです。 RESTful な WebAPI を設計しようとすると、細かなところで長考したり議論したりすると思います。また、他の API に倣ってやってはみたものの、本当にそれでいいのか、どうしてそうしているのか分からない、何てことも少なくはないと思います。 この記事では、そのようなハマリどころについて Vinay さんなりの答えを提示し、簡潔かつ明快に解説してくれています。 今後 WebAPI を設計される方は、是非参考にしてみてください。 なお、誤訳がありましたら編集リクエストを頂けると幸いです。 まえがき アプリケーションの開発が進むにつれて、その WebAPI を公
アプリクライアントがリソース指向なサーバAPI設計に期待すること - Qiita
酔いどれ設計ナイト2019 - connpassの発表資料です。 イベントのテーマ 「DB設計とAP設計をつなぐナニカ」 ということでこの記事では、アプリケーションサーバの利用者であるクライアントの視点から、どういう構造が嬉しいのか語ります。 自己紹介 iOSアプリ設計パターン入門という本の前半で、「設計とは何か」という主語の大きい話をしたり、GUIアーキテクチャの40年の歴史をまとめたりしました 題材をSwiftに絞っただけで、内容としては他プラットフォームにも通用する感じのやつなのでよかったらおひとつどうぞ Qiitaだと、お前らがModelと呼ぶアレをなんと呼ぶべきか。近辺の用語(EntityとかVOとかDTOとか)について整理しつつ考える - Qiitaという記事がよく読まれてます 議論の前提 今回の議論にはいくつかの前提があります。 クライアントチームとサーバチームが充分に協調し
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
IMI 情報共有基盤 コンポーネントツール
認証しないWeb認証 限定公開URLのセキュリティについて考える 公開版
Dockerを使った軽量なFastAPIの開発環境を構築 - Qiita
httpbin.org
HTTP status code for update and delete?