Blog | Giacomo Cerquone
  • The Web Api, a small but handy book


    Hello my boys, here we go with another little book review.
    Lately I’ve been reading here and there and among all the stuff I’ve read, only two books were about computer science. This one is on programming (actually it’s more a collection of guidelines to write good code than a real programming book) and the other one is the semi-biography of Linus torvalds (that I enjoyed really a lot) of which I’ll write up about.

    The paper I’m going to talk about in this post is titled: “The Web Api: Design Guidelines for Happy Developers“ and its writers published it on leanpub for free. There is also a purchasable edition on Amazon for kindles and it’s just ten pages longer.
    It has been published on a facebook page by one of the two writers (Federico Pinna) and after reading it, after all it’s just 30 pages long, I gave him some thoughts on the book.

    Why isn’t it a programming book?

    Being it a guidelines book, it’s just a collection of advices to build robust, intuitive and easy to understand API in order to make other programmer’s life easier. It never shows you a line of code but illustrates you concrete examples on well known metodologies for documenting your API, giving it the right URLs design, using the right HTTP method to manipulate your data and handling correctly errors and response statuses.

    No code? Isn’t it a bit strange?

    Yes, it is for me and it’s the exact same thing that I told to the writers. They could’ve written just some examples using different languages (or sticking always to the same) in order to let people grasp this concepts even better. In fact they assured me that in the next version of the book they’ll put some trivial but functioning examples of an API written in some language.

    To whom this book is directed?

    and does it stick to the REST architecture?

    First of all, it isn’t necessarily a book for experienced programmers (which they can find useful tips anyway). Actually I find it a “must have” for beginners because it gives you pretty much a strict idea of what you’ll be building if you’ll build APIs and also very useful advices to build them in a smarter and more efficient way.
    Concerning the REST architecture, this book does not follow it because they retained this “standard” too strict and quoting the book, this is what they say:

    We don’t like to call them REST, as we don’t want to introduce unneeded constraints in our guidelines.

    I personally disagree with this, and as I said to them, I’d have been pleased to know that a brand new paper in 2017 sticks to the standards defined exactly for making programmer’s life easier.
    Being a company or an open source developer, I want to be sure that I’m sticking to certain guidelines when I’m writing my software, because when I’ll want to hire or to receive a contribution for my open source project, I want the programmers to know as much as possible about my code even before reading it and if this is feasible through standard’s adoption, you must adopt them.

    Conclusion

    Considering the length and its being free, I think you should download and read it just for fun, it can always come in handy ;)

    Share this post on: