Wordな職場にSwaggerを定着させようとして失敗したけど結局定着した話 - Qiita
はじめに 私の職場では、WebAPIの仕様書をWordで書く習慣があったのですが、2018年頃にSwaggerで書くように切り替わったので、そのように変化した経緯を書きます。 何かの参考になれば幸いです。 ちなみに、こちらの記事と同じ職場です。 Wordな職場にMarkdownを定着させるためにやった４つのこと Swaggerとは？ Swaggerとは、REST APIの仕様を定義するためのフォーマットです。その周辺技術も含めて、Swaggerと呼ばれます。以下の記事が非常に参考になりますので、詳細を知りたい方はご参照ください。 Swaggerの概要をまとめてみた。 Swagger 導入失敗 2016年頃のある日、上司から「世の中にはSwaggerというものがあるらしい。調べてもらえる？」と指示されました。 調べてみたところ、Swaggerがあれば、WebAPIのドキュメントサイトも作れる
HTTPステータスコードを適切に選ぶためのフローチャート : 難しく考えるのをやめよう | POSTD
HTTPステータスコードを返すというのはとても単純なことです。ページがレンダリングできた？よし、それなら 200 を返しましょう。ページが存在しない？それなら 404 です。他のページにユーザをリダイレクトしたい？ 302 、あるいは 301 かもしれません。 I like to imagine that HTTP status codes are like CB 10 codes. "Breaker breaker, this is White Chocolate Thunder. We've got a 200 OK here." — Aaron Patterson (@tenderlove) 2015, 10月 7 訳：HTTPのステータスコードのことは、市民ラジオの10コードみたいなものだと考えるのが好きです。「ブレーカー、ブレーカー、こちらホワイト・チョコレート・サンダー。200
Web API設計指針を考えた｜デロイト トーマツ ウェブサービス株式会社（DWS）公式ブログ
小文字のみを使用する。 単語をつなげる必要がある場合はダッシュを利用する。 単数形よりも複数形をつかう。なお、実装がRailsの場合でテーブルの複数形が誤っている場合には、URLは正しい複数形としてRails側を修正する。（APIに実装を反映させるべきではない。） スペルミスをしない。 URLの階層は浅く保ち、複雑さはクエリパラメーターに押しこむ。 クエリパラメータ名は配列で複数渡すものについては複数形、一つだけ渡すものについては単数形とする。 ページングにはper_page、pageというパラメータ名を使用する。 と書いてきたが、ただし、RESTには必ずしもこだわらず、あくまで利用側の利便性を重要視した設計とする。 1つの作業を完結するために複数回のアクセスを必要とするようなAPIの設計はChatty APIと呼ばれる。これはネットワークのトラフィックを増加させ、クライアントの処理の手間
Representational State Transfer (REST)
[Top] [Prev] [Next] CHAPTER 5 Representational State Transfer (REST) This chapter introduces and elaborates the Representational State Transfer (REST) architectural style for distributed hypermedia systems, describing the software engineering principles guiding REST and the interaction constraints chosen to retain those principles, while contrasting them to the constraints of other architectural s
Swaggerを使ってインタラクティブなWeb APIドキュメントをつくる - Qiita
この記事は、微妙に以下の記事の延長線上です。わかりにくければ、こちらから読んでいただいた方がいいかもしれません。 LittleBitsを使ったIoTをつくり、家の室温変化のグラフをインターネットから見る（前編） - Qiita 「インタラクティブなWeb APIドキュメント」とはどういうものか Swaggerというツールを使います。Web APIをYAMLで書いておいて、Swaggerでサーバを立てると、読むだけのドキュメントではなくて、以下のようにパラメータを指定して実際にHTTPリクエストを送ることができるWebページが生成されます。 以下が返ってきたレスポンスです。 以下は実物です。ご自由に動かしてみて下さい。 インタラクティブなWeb APIドキュメント まだちょっと分かりにくいという方のために、アノテーションからドキュメントを作れるswaggerの使い方 - gong023の日記
【図解】RESTful WebサービスにおけるHTTPステータスコード : アジャイル株式会社
RESTful WebサービスではHTTPステータスコード=処理結果 弊社 アイコン認証Webサービス は、REST方式のWebサービスとして実装されています。 REST方式でない通常のWebアプリケーションでは、通常HTTPステータスコードとしては200(OK)しか返されません。 エラー等の状態を表す場合でもHTTPステータスは200(OK)が返され、画面に表示される内容にエラーを表すメッセージ等を含ませる事によって状態を表現します。 RESTfulなWebサービスを実現する場合には、処理結果はHTTPステータスコードで表現するべきとされています。 理由としては、以下のものがあげられます。 適切なHTTPステータスコードを返さない ( 全部 200 (OK) とかの ) 場合、エンティティの中身を解析しなければ、処理結果が判別できない。 Web標準に従う事で、HTTPステータスコードから
RESTのベストプラクティス | POSTD
現在ではREST APIはとても一般的な話題です。ほとんどすべてのWebアプリケーションの一部分となっています。シンプルで一貫性があり実際的なインターフェースは必須です。これは皆さんのAPIを他の人が使うことをとても容易にします。皆さんにとってはRESTの実践が日常的に感じられるかもしれませんが、RESTをあまり尊重しない人々もよく見かけます。これがRESTについて投稿するきっかけでした。 この記事にはRESTfulなAPIを設計する時に考慮すべきベストプラクティスがあります。 注意 : ここでのベストプラクティスは、私が過去の経験に基づいて良いと考える事例です。もし違う考えをお持ちであれば、お気軽にメールをくだされば意見交換できると思います。 APIのバージョンを示す APIのバージョンは必須であるべきです。これがあると時間が経ってAPIが変わっても影響を受けません。その方法の1つはUR
RESTful#とは勉強会2はすごかった | いきあたりばったり
先月末にRESTful#とは勉強会2を開催してきました。 これがもう！！！！本当に良かった！！！！勉強になった！！！まだ興奮冷めやらぬ感じです。 勉強会1回目が終わり、得たRESTの知識を私はすぐ実践に生かすことが出来ました。 「これはURLとアクション考えるとControllerもう1個用意する？」なんて会話も出るようになり、レベルアップした感があります。 2回目はどうしようかなとぼんやりしていた時に見た このスライドが大変興味深くて、他にもSlideShareのREST関係も徘徊しましたが、これが一番鷲掴みされました！！！ （レベルが上がってからまた徘徊すると、他の難しいと感じたものにも鷲掴みされるのかもしれませんね。楽しみ。） 「これは皆読むべき！そしてちゃんと理解できるようになりたい！」と思い、「WEBを支える技術」を見返したところ、最後の5部が「WEBサービスの設計」でしたので、
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
これから始めるエンタープライズ Web API 開発 | オブジェクトの広場
[REST] 認証が必要な API を REST っぽく作るときのメモ - それはBooks