I am starting to write a webservice, and I've built with nodeJS and a RESTfulish approach.

From what I gather:

  • The advantage is that you don't have to duplicate code.
  • The disadvantages are that you:
    • will update the public API frequently, but should be solved with versioning
    • can't really make service specific caching and optimizations

What is considered best practice? Do sites such as Stack Exchange, Github, Twitter, etc use their own APIs for their clients?

  • 12
    Eating your own dogfood will also drive you to improve your public API – Ben Brocka May 14 '12 at 14:21
  • That is how Amazon does it. – OliverS May 14 '12 at 15:39
  • 3
    To add to OlverS's point, see Google Platforms Rant – Brian May 14 '12 at 20:37

You should absolutely use your own API. This concept is widely known as dogfooding and it has many benefits beyond avoiding code duplciation.

  • Consistent behaviour between your site/product and what API consumers will write (ie. their expectations of your API)
  • Another form of testing.
  • You can and will find bugs in the API before your customers do, making their resolutions cost less.

Although I would argue against one of your points: you should not be updating the API frequently. Spend the time to architect and proof out an API that will stay around for a while. Fortunately, dogfooding in this way will enforce that. Where you would have just broken customer code before, you'll now be breaking your own code. When you must, yes versioning is a solution, but it should be avoided.

| improve this answer | |

for some reason it won't let me log in as the poster of the question, but it was me. I can't accept your answer, wish I could, it makes a lot of sense.

However, how can you not want to update your API? What about adding new features, removing unpopular ones, refactoring, etc?

| improve this answer | |
  • Hey. This should be a comment on his answer - but I don't think you have enough rep to comment. Anyway, the point is that you shouldn't update the API frequently. And even then, adding new features is no problem - it can't break existing code. Why remove unpopular ones? Make them deprecated, and remove sometime in the future after people have had a long time to respond to the deprecation. – Max May 15 '12 at 12:09
  • 2
    Adding methods to an API is fine, changing an existing API is bad because it will break any code that depends on the API. – Bryan Oakley May 15 '12 at 13:01
  • @stanm87: Max and Bryan said it well. You should avoid changing the contract of your API (that is, the interface and the expected, working, behaviour). People will depend on that if they will use your API and if you change it, it will break their code. – Steven Evers May 15 '12 at 13:09
  • thanks a lot for clarifying. @Max I indeed cannot comment on his answer – stanm87 May 15 '12 at 20:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy