TDD your API • Hacker News Board

Re: TDD your API

#31

Post by steveklabnik » Fri, May 16, 2014, 10:49 PM UTC

ryanfitz wrote: post #25

IgorPartola wrote: post #22

So I recently created a simple RESTful API. Nothing fancy here in 90% of the resources. 10% do some funky things (BTW, which HTTP verb should /login use? POST? You are not creating anything? PUT? PATCH?! Really it should be a GET in this case as I am just retrieving a pre-generated token...). I did add a set of tests to keep me honest about what the API should do. I added them after the API was completed, and based o…

I recently created a login flow for a RESTful API. The solution I went with was instead of thinking of it as a high level activity such as login, what I was really doing was creating auth tokens to then be used in the Authorization header in subsequent requests. I created a /tokens endpoint, where I POST the auth credentials and in return I get back a newly generated auth token. In my opinion this is a nice RESTFul s…

This is actually exactly how we model API tokens: https://docs.balancedpayments.com/1.1/api/api-keys/#create-a...

Re: TDD your API

#32

Post by benihana » Fri, May 16, 2014, 11:11 PM UTC

shadowfiend wrote: post #3

The article is very interesting/good, but I do want to mention one issue I have with it: “To say that there’s a large amount of literature on the benefits of this approach would be an understatement.” I've brought this up before, but “literature” carries the connotation of “scientific literature”, and I actually haven't heard of many rigorous, well-constructed scientific experiments that have produced conclusive scie…

>I've brought this up before, but “literature” carries the connotation of “scientific literature”

to you. That connotation didn't even cross my mind. Regardless. Are you going to wait until there is a peer-reviewed scientific paper telling you TDD is good before you'll believe it? Do you have personal experience that TDD seems to make your designs better? If so, is that less true to you because we haven't scientifically "proven" it?

Re: TDD your API

#33

Post by mneary » Fri, May 16, 2014, 11:34 PM UTC

zdne wrote: post #14

mneary wrote: post #2

I had a similar goal, and built a simple shell script[1] that would enable its user to write tests as curl requests. [1]: http://mattneary.com/Quizzical/

This looks interesting! Might be worth taking a look at the library we have built to validate the HTTP messages using `curl-trace-parser` ( https://github.com/apiaryio/gavel )

Thanks, I will definitely look into that.

Re: TDD your API

#34

Post by mneary » Fri, May 16, 2014, 11:36 PM UTC

mtamizi wrote: post #6

mneary wrote: post #2

I had a similar goal, and built a simple shell script[1] that would enable its user to write tests as curl requests. [1]: http://mattneary.com/Quizzical/

The challenge we had with that approach was being able to reference the response of a previous request. As a simple example: 1. Create customer 2. Add tokenized card to customer 3. Charge the card Step 2 requires the HREF/ID of the customer. Step 3 requires the HREF/ID of the card.

Yeah, I realized the same thing; this aspect really makes it harder to keep the system simple, naturally. I've thought about different ways of approaching this, considering chained requests as a possibility.

Re: TDD your API

#35

Post by e1g » Fri, May 16, 2014, 11:42 PM UTC

benihana wrote: post #32

shadowfiend wrote: post #3

The article is very interesting/good, but I do want to mention one issue I have with it: “To say that there’s a large amount of literature on the benefits of this approach would be an understatement.” I've brought this up before, but “literature” carries the connotation of “scientific literature”, and I actually haven't heard of many rigorous, well-constructed scientific experiments that have produced conclusive scie…

>I've brought this up before, but “literature” carries the connotation of “scientific literature” to you . That connotation didn't even cross my mind. Regardless. Are you going to wait until there is a peer-reviewed scientific paper telling you TDD is good before you'll believe it? Do you have personal experience that TDD seems to make your designs better? If so, is that less true to you because we haven't scientific…

The trend "Jabberwocky" comes at a very considerable startup cost, a significant learning curve, and a negative impact productivity (at least during the early days). In return for strict adherence to its philosophy, it promises to possibly help you create a better designed and more reliable system over the long run. Some cool cats are using Jabberwocky, many more denounce it. Some studies claim it's at least not harmful, others say it's a bureaucratic add-on.

Meanwhile, you mostly deal with small, simple, or short-lived systems and have little expectation in building skyscraper enterprise apps, so the promised benefits fall in the "oh that's nice" bucket. Or perhaps you lead a team that is deeply invested in a three-year codebase not using Jabberwocky, and the cost of getting everyone to switch has a serious financial implication.

The stance of "Jabberwocky sounds nice enough, but I do wonder if anyone systematically proved it is worthwhile" is a perfectly valid position. It is not about what you should do, it is about what you can do, and you can't just follow every trend (also see: Agile+XP) or even trial every alternative. For many non-engineering firms, there is "real work" to be done, and the never-ending increasingly expensive pursuit of operational excellence can be a hard thing to sell internally.

This is a huge benefit of science of the rest of us - a few million people can experiment on the edge of what is known, most of them will get nowhere, but a few thousand will determine that "X448YAB" tends to be superior to "X28YNB". Over time, the rest 7 Billion of us will slowly migrate to the more effective way of doing things and everyone benefits. We cannot denounce someone for not using stuff from the cutting edge until that thing is proven effective.

Re: TDD your API

#36

Post by patrickmclaren » Fri, May 16, 2014, 11:48 PM UTC

benihana wrote: post #32

shadowfiend wrote: post #3

The article is very interesting/good, but I do want to mention one issue I have with it: “To say that there’s a large amount of literature on the benefits of this approach would be an understatement.” I've brought this up before, but “literature” carries the connotation of “scientific literature”, and I actually haven't heard of many rigorous, well-constructed scientific experiments that have produced conclusive scie…

>I've brought this up before, but “literature” carries the connotation of “scientific literature” to you . That connotation didn't even cross my mind. Regardless. Are you going to wait until there is a peer-reviewed scientific paper telling you TDD is good before you'll believe it? Do you have personal experience that TDD seems to make your designs better? If so, is that less true to you because we haven't scientific…

It is indeed less true, until the possibility that we could be committing a type I error can be ruled out.

It may be that TDD has little negative effect upon development and results in a FeelGood™ response that could be present within any project with non-zero productivity.

Re: TDD your API

#37

Post by Spearchucker » Fri, May 16, 2014, 11:53 PM UTC

This is great, totally see the value for an API. I'm interested to know what people use for say, native desktop apps, which is what I'm building.I ask because I've tried writing a few tests a couple of years ago, didn't see the point and haven't written any since. My code is stable, it's dogfooded every single day. Anyone have any thoughts on TDD in this kind of scenario?

Re: TDD your API

#38

Post by pault » Fri, May 16, 2014, 11:53 PM UTC

shadowfiend wrote: post #3

The article is very interesting/good, but I do want to mention one issue I have with it: “To say that there’s a large amount of literature on the benefits of this approach would be an understatement.” I've brought this up before, but “literature” carries the connotation of “scientific literature”, and I actually haven't heard of many rigorous, well-constructed scientific experiments that have produced conclusive scie…

I don't understand how anyone can develop software with myriad moving pieces without isolating and testing each component as it is written. It's like trying to figure out why your car won't start by sitting in the driver's seat and pushing buttons. I wouldn't ever presume to tell someone else how to do their job, but I can't imagine doing it any other way. (I prefer to write out my spec in BDD style, and unit test when the logic gets hairy).

Re: TDD your API

#39

Post by patcon » Fri, May 16, 2014, 11:55 PM UTC

Funny. I read this title, and thought "Oh, like Balanced Payments does", and they I read the brackets :)

Re: TDD your API

#40

Post by mtamizi » Fri, May 16, 2014, 11:59 PM UTC

mneary wrote: post #34

mtamizi wrote: post #6

Earlier quoted context omitted.

The challenge we had with that approach was being able to reference the response of a previous request. As a simple example: 1. Create customer 2. Add tokenized card to customer 3. Charge the card Step 2 requires the HREF/ID of the customer. Step 3 requires the HREF/ID of the card.

Yeah, I realized the same thing; this aspect really makes it harder to keep the system simple, naturally. I've thought about different ways of approaching this, considering chained requests as a possibility.

Here's an example of how we do it:

The scenario: https://github.com/balanced/balanced-api/blob/master/feature...:

  Scenario: Push money to an existing debit card
    Given I have sufficient funds in my marketplace
    And I have a tokenized debit card
    When I POST to /cards/:debit_card_id/credits with the JSON API body:
      """
      {
        "credits": [{
          "amount": 1234
        }]
      }
      """
    Then I should get a 201 Created status code
    And the response is valid according to the "credits" schema
    And the fields on this credit match:
      """
      {
        "status": "succeeded"
      }
      """
    And the credit was successfully created

There's several things in there like "And I have a tokenized debit card" that setup the scenario to be able to do things like "/cards/:debit_card_id/credits", which refers to an actual card ID created in the test API.