REST APIドキュメント生成パターン - ✘╹◡╹✘
REST API用のドキュメントを生成するときにどうやってるかについて雑記を残しとく。 概要 実装とドキュメントの乖離を避けるためには、同じ意味情報を二箇所以上に定義することを避ける必要がある。そのための方法として、実装それ自身か、もしくは実装が参照している何らかのメタデータを元にしてドキュメントを生成したり、テストの実行結果からドキュメントを生成するというパターンがある。 テストから Cookpadでは、autodocというライブラリを利用して、RSpecでテストを実行している途中で得られたメタデータからドキュメントを生成している。これはテストの実行結果からドキュメントを生成するパターン。 これは実現方法としてはかなり特殊な部類。このパターンが最も効果的に働くのは、ドキュメント生成のために余分な開発コストはあまり掛けたくないが、テストは真面目に書いている OR 真面目に書いてほしい、とい
じんもんそんで使えそうなデータやAPI等のリスト | Digital Humanities notes in Japan
以下、とりあえずとってきて色々いじることができそうで、人文学研究に役立ちそうなデータをリストします。（by 永崎研宣） 日本編 近代語のコーパス（国立国語研究所） http://www.ninjal.ac.jp/corpus_center/cmj/ コーパス開発センター（国立国語研究所）-近代文語Unidic、中古Unidic等もあり http://www.ninjal.ac.jp/corpus_center/ 参考： オープンソースの日本語形態素解析エンジンMecab https://code.google.com/p/mecab/ オックスフォード上代日本語コーパス http://vsarpj.orinst.ox.ac.uk/corpus/ 日本語テキストイニシアチブ http://jti.lib.virginia.edu/japanese/index.euc.html 青空文庫 ht
ダミーのJSONデータを自動生成してくれるサイト「JSON GENERATOR」 | ライフハッカー・ジャパン
「JSON GENERATOR」はダミーのJSONデータを自動生成してくれるサイトです。JSONでテストデータを作りたいときに便利です。たとえばダミーの名前や電話番号、住所などの情報を自分で考えるのは面倒です。このサイトを使えば、作成したいJSONの形式を指定するだけで、ランダムな情報を自動生成してくれます。 以下に使ってみた様子を載せておきます。まずJSON GENERATORへアクセスしましょう。左側が自分が作成したいJSONデータの形式です。キーは指定しておき、値にどんな情報が欲しいか入力しておきます。 右側が自動生成されたダミーのJSONです。値にランダムな情報が入力されていますね。キーさえ指定しておけばあとは自動的に対応する値をいれてくれるのは非常に助かります。ぜひJSONでダミーデータを作成したいときにご活用ください。 JSON GENERATOR （カメきち）
Web API: The Good Partsを読んだ - AnyType
Web API: The Good Parts 作者: 水野貴明出版社/メーカー: オライリージャパン発売日: 2014/11/21メディア: 大型本この商品を含むブログ (1件) を見る 業務ではiOSアプリとバックエンドの開発を両方担当しているので、APIの設計を何回かやってきた。しかし、自分なりのやり方でやってきた部分が多かったので、最近発売されたWeb API: The Good Partsを読んでちゃんとした設計について学ぶことにした。 得られた学びをメモとして残す。 HATEOAS HATEOAS（Hypermedia As The Engine Of Application State）という設計方法を初めて知った。HATEOASではまず、サーバー側はレスポンスに関連するエンドポイントを含め次にアクセスするAPIを簡単に辿れるようにする。クライアント側は最初のエンドポイント以
Architecting RESTful Rails 4 API · Jesal Gadhia
Architecting RESTful Rails 4 API 22 Oct 2013 This is a follow-up to my previous post about Authentication with Rails, Devise and AngularJS. This time we’ll focus more on some aspects of the API implementation. One thing to keep in mind, where my previous example used Rails 3.2, I’m using Rails 4 this time around. Versioning If you are building an API which could be potentially consumed by many dif
小さなサーバーで大きなサービスをつくる | カメリオ開発者ブログ
アーキテクトのItoです。動画を撮るのが趣味ですが、最近はこの本を買って、カラーグレーディングの勉強をしています。とても良い本です。 さて、今回お話するのはバックエンドにあるフロントエンドについて。 以下はほぼ実際にカメリオで運用しているバックエンド構成です。 図中のサーバーというものはいわゆるHTTPベースのサーバーアプリで、ここでは緑をNode.js, グレーをPython, C++で実装しています。小さいサーバーがたくさんあります。主にクライアント〜フロントエンドAPIだけの構成図で、記事クローラーや各種管理画面などは図にはありませんが存在します。 まずフロントエンドにELB(AWSを使用)とNginxを置き、後ろに NodeベースのフロントエンドAPIサーバーを置きます。 ここはNode.jsで作られたアプリをサービスするごく一般的な方法です。 エンドポイント(api.kamel.
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
背景 APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なREST APIドキュメントを作成する - Qiita これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。 markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
Garage RailsでOAuth認証付きのRest APIをお手軽開発！
CookpadさんがOSSで先日OSSで公開されたGarageはRestfulなAPI + OAuth(Doorkeeper)をワンストップで提供してくれるgemです。 ちょうど触る機会が出てきたので、今回四苦八苦しながら使ってみたのでそのメモです！ 🎂 今回のサンプル実装今回はOAuthで認証して、次のシンプルなAPIにアクセスできるようにするまでのサンプルを作成します。 GET /v1/users => ユーザーのリスト出力 GET /v1/users/:id => 個々のユーザー情報の出力 🎃 Gemの追加Gemfileに以下を追加して、bundle install。 gem 'garage', github: 'cookpad/garage' gem 'responders', '~> 2.0' # If you use Rails4.2+ group :development
Web API: The Good Parts
Web APIの設計、開発、運用についての解説書。APIは設計次第で使いづらいものになってしまうだけでなく公開後の保守運用も難しくなってしまいます。そのためAPIを美しく設計することがとても重要です。本書では「設計の美しいAPIは、使いやすい、変更しやすい、頑強である、恥ずかしくない」という考えのもと、APIをどのように設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにします。ターゲットは、URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなタイプ――XML over HTTP方式やJSON over HTTP方式――のAPIです。読者は、Web API設計の考え方と手法を知ることができます。 はじめに 1章 Web APIとは何か 1.1 Web APIの重要性 1.1.1 APIでの利用を前提とした
Grape で API を複数ファイルに分けて定義する - present
Grape では 1 ファイルに API をずらっと書けるけど、 規模が大きくなってくると見通しが悪くなるので、複数ファイルに分割したくなる。 Grape では API が他の API をマウントできるので、 その機能を使ってリソースごとにファイルを分割できる。 以下、サンプル。ヘルパーも別ファイルに切り出してみた。 posts.rb # coding: utf-8 module API class Posts < Grape::API resource :posts do desc "投稿をすべて取得" get do # posts はヘルパーメソッド posts end desc "投稿を1件取得" get ":id" do posts.find(params[:id]) end end end end helpers.rb # coding: utf-8 module API mod
Dropbox アカウントひとつで利用できるプッシュ通知機構 : DSAS開発者の部屋
2018年6月追記： Dropbox API の仕様変更により以下の内容はすでに obsolete です。記事は残しますが、過去の情報であることをご了承下さい。 Dropbox 社は広く知られるファイル系のサービスとは別に 2013年より非ファイル形式の構造化データの保存・読み出しに対応するデータストアサービスを公開しており、Dropbox アカウントを持っていれば Dropbox Datastore API 経由でこのサービスを利用できます。同 API は全体的にシンプルで SDK のサポート範囲も広いため自作のソフトウェアへ手軽に組み込むことが可能です。 自前でサーバ環境を構築・運用する手間なしにレコードイメージのデータをネットワークストレージ上で取り回せるのは便利で、また多くの人がアカウントを持っていることへの安心感もあり、この Dropbox のデータストアサービスはさまざまな用途
APIの後方互換性を保つ工夫 - ワザノバ | wazanova
Stripeの決済サービスの成長は、APIが使いやすいというエンジニアの間での評判がかなり寄与したと記憶しています。 同社のAPIは現在、 エンドポイント: 106 バージョン: 65 APIクライアント: 6 ユーザ企業を煩わせることなく後方互換性をしっかり担保したいという方針を守るための工夫を、Amber Fengが紹介してくれています。 1) ユーザが利用するバージョン情報の把握 ユーザ企業が最初にAPIコールをしたときのバージョン情報をStripe側で保管している。それ以降、ユーザ企業はバージョンのことを意識することなく、最初のバージョンのAPIを利用し続けることができるようにしている。ユーザ企業側でバージョンの変更をしたい場合は、ダッシュボードでの設定や、リクエストヘッダーに情報を付加することで可能。 2) バージョンと機能の整合性 YAMLファイルでバージョンとその振舞いの情報
はてなブックマークの人気エントリーもターミナルでみたいよね - ブクマ取得APIをRubyで使う
自分のブログの人気エントリーは、はてなブックマークのエントリーリストにサイトのURLを投げることで見ることができます。例えば、このブログ（hp12c）における人気エントリーを見るにはブラウザで以下にアクセスします。 http://b.hatena.ne.jp/entrylist?sort=count&url=http://melborne.github.io 人気記事上位20件が表示されます。ここでsortのパラメータにeidを渡すとブクマされたすべての記事から新着20件が表示され、またhotを渡すとブクマ3件以上の新着20件が表示されます。 ところでこれには対応する非公式のAPIがあってプログラムからアクセスが可能です1。 小粋空間: JSONP: 2012年6月 アーカイブ そうとなればRubyでアクセスしない手はないですよね。ちょうどこのブログはギットハブにおける諸事情によりドメイン
Hacker News API | Y Combinator
Today we’re excited to launch an official Hacker News API. We’ve partnered up with Firebase (YC S11) so that the data we’re making available will be near real time, which should be a huge improvement for developers who had to rely on scraping the site for this info. The API is available at https://hacker-news.firebaseio.com/ with some initial documentation and a few examples written by our own Nic
Railsでinitializersに書いた内容をdevelopmentモードで再読み込みさせる - Qiita
外部APIに接続するようなクラスの設計 Railsで外部のAPIサービスにつなぐクラスなどを書く際に、将来的にGemにすることを見越してできる限りそのプロジェクト自体に依存しないように設計すると思います。（ここでいう、「依存しない」とは、たとえばそのプロジェクトのSettingsLogicをこのクラスから見に行かないなど。） ここで、外部のAPIが接続時にAPIキーと、トランザクション毎に変わる情報を渡さないといけないとすると、APIキーは一度Railsを立ち上げると変わらないのでクラスに持たせて、トランザクションは引数で渡す、ということをやると思います。 class ExternalServiceAdapter include ActiveSupport::Configurable config_accessor :api_key def create_transaction(trans
Rails / Google Analyticsのデータを使って分析や管理画面のためのグラフをつくる
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 #lib/ga_api.rb require 'google/api_client' class GaApi KEY_FILE = "#{Rails.root}/certificate/xxxxxxxxxxx.p12" ACCOUNT_EMAIL = "[email protected]" KEY_SECRET = "xxxxxxxxxxx" VIEW_ID = "xxxxxxxxxxx" VERSI
"Microservices"を読んだ
James Lewis氏とMartin Fowler氏による“Microservices”を読んだ．以前ざっと目を通したが，最近よく耳にするようになったのでちゃんと読んだ．以下はそのメモ． 概要 “Microservices” とはソフトウェアシステムの開発スタイルである 近年このスタイルでの開発を見てきて良い結果が出ている 初出は2012年の3月の“Micro services - Java, the Unix Way” Microserviceは一連の小さなサービスで1つのアプリケーションを開発する手法 それぞれのサービスは自身のプロセスで動いており，軽量な機構（e.g., HTTP API）を通じて情報をやりとりする これらのサービスは独立して自動デプロイされる 一枚岩として構築されるMonolithicスタイルのアプリケーションと比較すると分かりやすい 一般的なエンタープライズのア
APIドキュメントを実装と乖離させないために - Qiita
内部用APIであるか外部の開発者向けのAPIであるかに関わらず、ドキュメントと実装との乖離は極力避けたいものであるが、注意深く開発を進めない限りこの状況は容易に起こり得る。何が乖離を引き起こし、どうすればこの状況を回避できるのか考えながら、JSON Schemaの利用例を紹介する。なおこの投稿では、HTTP経由でデータの通信を行うような狭義のAPIのことをAPIと呼ぶことにする。 同じ情報源を参照する APIドキュメントと実装が同じ情報源を参照するようにすれば、論理的に関連した要素は統一的に変更され、これらの変更は完全に同期が取れたものになる。つまり、変更時に乖離が生じにくくなる。但し情報の見せ方によって乖離が発生する可能性は十分にだろうし、乖離が発生するのは理解しようとする側の認識の問題であるから、論理的に全く起こり得ないということではない。 この参照の形には、両者が別の情報源を参照する
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
https://staff.aist.go.jp/tanaka-akira/pub/rubykaigi2006-06-10.pdf
GitHub - cookpad/garage: Rails extension for RESTful Hypermedia API
