Skip to content

Commit

Permalink
Unpack "in-app JavaScript client"
Browse files Browse the repository at this point in the history
  • Loading branch information
Laila Winner committed Nov 23, 2015
1 parent 3e2c9db commit c7eb113
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions best-practices/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

2 comments on commit c7eb113

@boddhisattva
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@malandrina Thanks for making the wording more descriptive based on the discussion here. There's just one more thing on the top of my mind currently based on the above guideline, I was wondering why there isn't a mention of writing controller specs for the API end points that would check for things like the returned HTTP status codes. I'm assuming these wouldn't be tested as part of feature specs and I'm not quite sure on whether they're tested in request specs. Is it supposed to be considered implicitly that one needs to write controller specs in addition to what's mentioned in the above guideline? . Please feel free to correct me if I'm missing something here.

@malandrina
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@boddhisattva, good question. Request specs usually include assertions about HTTP status codes, per this example.

You’re correct that feature specs aren’t meant to include assertions about the HTTP status codes returned by API endpoints. The thinking behind this guideline is that if the JSON API is consumed by a web client that ships with the provider of the API (aka an in-app JavaScript client), it’s more beneficial to exercise our API endpoints in feature specs than controller specs.

In this scenario the HTTP status codes can be viewed as part of the underlying implementation of the behavior we want our users to experience when they use our application. Since we care more about the behavior than the underlying implementation, we can achieve a higher level of confidence in our application by exercising our API endpoints in feature specs. And since our JSON API isn’t available to clients other than the one we maintain, we don’t need to worry as much about the HTTP status codes returned by our API as we would if it were public.

It’s worth noting that this is just a guideline, though. There are, of course, exceptions to this overall strategy — there are cases where it makes sense to opt to write a controller spec instead of a feature spec for a given API endpoint.

Hope that helps illustrate the thinking behind this guideline!

Please sign in to comment.