From 556be5fd286b2fdbfff853d6447afb0f223c39ed Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Wed, 21 Oct 2015 11:23:06 -0700 Subject: [PATCH 1/6] Add best practices for building Ruby JSON APIs * Recommend that readers follow Heroku's HTTP API Design Guide when developing JSON APIs * Prefer `oj` for parsing JSON and RSpec request specs for integration testing, per iOS on Rails * References: https://github.com/thoughtbot/ios-on-rails/blob/master/book/rails/introduction.md#parsing-incoming-json-requests https://github.com/thoughtbot/ios-on-rails/blob/master/book/rails/creating_a_get_request.md#it-all-starts-with-a-request-spec --- best-practices/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/best-practices/README.md b/best-practices/README.md index dde51ab7..aaac31b1 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -329,3 +329,14 @@ Angular [annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails [ngannotate]: https://github.com/kikonen/ngannotate-rails [angular-translate]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive + +Ruby JSON APIs +-------------- + +* Follow Heroku's [HTTP API Design Guide] +* Use [`oj`][oj] for parsing JSON +* Write [request specs] for your API endpoints + +[HTTP API Design Guide]: https://github.com/interagent/http-api-design +[oj]: https://github.com/ohler55/oj +[request specs]: https://www.relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec From 4b3cd338e6ff18941662e1db5bf83d7714eee25e Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Fri, 23 Oct 2015 12:53:51 -0700 Subject: [PATCH 2/6] Make JSON parser recommendation less specific --- best-practices/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices/README.md b/best-practices/README.md index aaac31b1..3e183593 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -334,7 +334,7 @@ Ruby JSON APIs -------------- * Follow Heroku's [HTTP API Design Guide] -* Use [`oj`][oj] for parsing JSON +* Use a fast JSON parser, e.g. [`oj`][oj] * Write [request specs] for your API endpoints [HTTP API Design Guide]: https://github.com/interagent/http-api-design From 3e2c9db1364f4063d7e724b2d499e76e8a04fcb5 Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Fri, 30 Oct 2015 10:52:25 -0700 Subject: [PATCH 3/6] Use different integration testing strategies depending on API consumer --- best-practices/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/best-practices/README.md b/best-practices/README.md index 3e183593..785159e3 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -335,8 +335,11 @@ Ruby JSON APIs * Follow Heroku's [HTTP API Design Guide] * Use a fast JSON parser, e.g. [`oj`][oj] -* Write [request specs] for your API endpoints +* Write integration tests for your API endpoints. When the primary consumer of + your API is an in-app JavaScript client, write [feature specs]. Otherwise + write [request specs]. [HTTP API Design Guide]: https://github.com/interagent/http-api-design [oj]: https://github.com/ohler55/oj +[feature specs]: https://www.relishapp.com/rspec/rspec-rails/docs/feature-specs/feature-spec [request specs]: https://www.relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec From c7eb1135aa38a2d56686e94873e244fbd56b9688 Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Mon, 23 Nov 2015 10:39:30 -0800 Subject: [PATCH 4/6] Unpack "in-app JavaScript client" --- best-practices/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/best-practices/README.md b/best-practices/README.md index 785159e3..840c8f69 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -336,8 +336,8 @@ Ruby JSON APIs * Follow Heroku's [HTTP API Design Guide] * Use a fast JSON parser, e.g. [`oj`][oj] * Write integration tests for your API endpoints. When the primary consumer of - your API is an in-app JavaScript client, write [feature specs]. Otherwise - write [request specs]. + the API is a JavaScript client maintained within the same code base as the + provider of the API, write [feature specs]. Otherwise write [request specs]. [HTTP API Design Guide]: https://github.com/interagent/http-api-design [oj]: https://github.com/ohler55/oj From 4c65e69c1d678c9148e4e3b18a0f2c60ee08939f Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Fri, 8 Jan 2016 09:12:53 -0800 Subject: [PATCH 5/6] Recommend reviewing Heroku guidelines, not following --- best-practices/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/best-practices/README.md b/best-practices/README.md index 840c8f69..8440a604 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -271,7 +271,7 @@ Shell * Use the `local` keyword with function-scoped variables. * Identify common problems with [shellcheck][]. -[shebang]: http://en.wikipedia.org/wiki/Shebang_(Unix) +oshebang]: http://en.wikipedia.org/wiki/Shebang_(Unix) [parsingls]: http://mywiki.wooledge.org/ParsingLs [bashisms]: http://mywiki.wooledge.org/Bashism [shellcheck]: http://www.shellcheck.net/ @@ -333,7 +333,8 @@ Angular Ruby JSON APIs -------------- -* Follow Heroku's [HTTP API Design Guide] +* Review the recommended practices outlined in Heroku's [HTTP API Design Guide] + before designing a new API. * Use a fast JSON parser, e.g. [`oj`][oj] * Write integration tests for your API endpoints. When the primary consumer of the API is a JavaScript client maintained within the same code base as the From 9665248cbc929b41a8c0b7f498313e84789de0ea Mon Sep 17 00:00:00 2001 From: Laila Winner Date: Fri, 8 Jan 2016 09:30:39 -0800 Subject: [PATCH 6/6] Fix typo --- best-practices/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices/README.md b/best-practices/README.md index 8440a604..c43f7b0c 100644 --- a/best-practices/README.md +++ b/best-practices/README.md @@ -271,7 +271,7 @@ Shell * Use the `local` keyword with function-scoped variables. * Identify common problems with [shellcheck][]. -oshebang]: http://en.wikipedia.org/wiki/Shebang_(Unix) +[shebang]: http://en.wikipedia.org/wiki/Shebang_(Unix) [parsingls]: http://mywiki.wooledge.org/ParsingLs [bashisms]: http://mywiki.wooledge.org/Bashism [shellcheck]: http://www.shellcheck.net/