Today I was fortunate enough to present at one of the Cloud Lunch and learn events (you can register for any of the events here and see previous sessions here). One of the questions asked at the end of the session was recommended reading on APIs. So I’ve gathered up some links to books I’d suggest worthwhile reading I’d suggest:
Enterprise API Management: Design and deliver valuable business APIs by Luis Weir (Amazon.co.uk)
I should also mention an API book I’ve co-authored. While it focuses on an Oracle product, there is a lot of content that is relevant to any API development using an API Gateway (Amazon.co.uk). I’ve not looked at all the books at API-University, but from I have seen the content is worth examining.
The slides for my presentation can be found on slideshare, and here:
I wrote a blog after completing my first book with Robert van Mölken about what was involved. That post can be seen here. It focussed on the processes with Packt and how Robert and I worked to try to ensure the book felt consistent despite the two of us writing.
Writing Logging In Action was a solo project for a different publisher. It seems like an opportunity to share some fresh insights.
Time and Effort
Surprisingly the time between signing the contract and the manuscript being completed ready to go through the final production process didn’t vary hugely roughly 15-18 months. The final steps of preparing to go to print did take longer, in part down to the number of extra steps taken by Manning to ensure the book was polished. Upon reflection, I think that is at least partly down to the fact you need the chapters to need to flow, particularly when one chapter leads directly to the next. So you do get periods of respite until your co-author has got sufficiently far enough with their writing to enable you to start the next part. Writing solo, as soon as one chapter is completed you’re into the next, so no periods of respite.
When it comes to the amount of actual time involved. That is different, I didn’t keep track exactly. But knowing what I typically did each week and roughly how many quiet periods I had I think it works out to be 300 hours give or take 50 hours. That sounds a lot, but then if you look at it as 1 hour per page it doesn’t seem too significant.
Using Time and Self Discipline
The way time is used has been a little different, when co-authoring you have to allow time for coordinating and supporting each other, peer-reviewing writing pushing each other along in terms of keeping to plan. The Manning development team are pretty good at keeping you moving without it feeling like you’re being chased, and will provide constructive and supportive feedback. But your co-authors will know the subject matter very well and know what your best work is like, so are able to challenge you when peer-reviewing the work. When we wrote the API book, I remember one of my colleagues reviewing a chapter and coming back saying it was a solid chapter, but I know you have explained these ideas more clearly. When I went back over the chapter, I could see what they meant. As a result a better book.
The bottom line is it can be difficult to bring a critical eye to your own work, particularly soon after have written it. But you do need that self-discipline when working on your own. This is where the Manning editorial team really stood out.
The book is published, that’s the end?
It is easy to think that’s the end of things, and certainly in terms of solid writing it is. But after all the invested effort in writing it. You might as well help promote the book and take advantage of the reputation of being a published author. This means presenting on the subject of your book. The book will provide a level of credentials & credibility to the subject you’ve written about. Despite being an introvert (which is why I take pleasure in the writing process) getting through the pre-presentation nerves, feelings of imposter syndrome once on stage and talking about your subject can be a rush, particularly as you finish. The personal payoff from presenting can come after the event, when someone who has seen your presentation says to you afterwards, that really helped me, or they really enjoyed or found the presentation thought-provoking.
If presenting is too much then these days there are other paths available, such as writing articles for journals, participating in podcasts. Having participated in several podcasts if you have a good host, this can be good fun.
What do I get out of writing?
The benefit of royalties certainly won’t replace a typical developer’s salary, unless you’re really lucky. Even with mainstream publications, only a small proportion of authors are successful enough for it to become their day job. But, there are indirect benefits. If you want something to put your CV above many others – then a book will really help. This is often why a lot of freelancers write books – it helps provide credibility over others. There is no doubt that my writing has made a difference to a change in job. I suspect that joining Capgemini and my next move has been a lot easier because of it. Not to mention, I’ve known clients like the idea that within the team they’ve engaged are people with credibility beyond just the supplier. Depending upon your employer, the marketing value for them to employ you (or me) as an author (and by implication an SME) add differentiation as well.
Writing solo again?
I’ve heard technical book authors say, never again once they’ve been published. A few I know have written multiple books. Given the experience, I think co-authoring is easier. But the gratification of completing a solo effort is so much greater.
The technical book landscape is shifting, technology cycles seem to be accelerating (or is it that I’ve reached an age where time seems to go by so much quicker) which is impacting a book’s shelf life. The ability to provide, receive and expect more interactive engagement is evolving – LiveBooks, Katacoda etc. The need to consume smaller pieces across multiple sources is growing as we need to build new skills, but don’t want to start from scratch (as I described here for example).
There is no doubt I’ll get involved in another book project. But a solo writing project will probably be smaller so we can shorten that development cycle.
In January we presented our 1st online training, looking at API Design and use of Apiary and Swagger. Things went well until near the end where for some reason voice and video dropped for no apparent reason. Our coordinator Lindsay kept the recording going and soon as we reconnected I continued the session and went through the Q&A.
So if you missed the end of the training, please do check back with the recording.
If you missed the training – we’ll be rerunning in March – go here.
For those on the training will have seen at the start of the training links to my social media profile, so happy to try to respond to any further questions.
We are also scheduled to run the session again in a month or so.
One of the questions received during the session I thought worth mentioning was when would Apiary support Open API 3.0. Well according to their blog very soon, looking forward to it as the OAS 3 does look a little cleaner.
My next Packt project (via O’Reilly) is not a book, but a short online training course about good API design, API 1st and some tools that can support an API 1st methodologies. Register for the session here.
It includes a closer look at cloud tools such as Oracle’s excellent Apiary (sorry if this sounds like a sales pitch, but it is a good tool and the words of the found of RestLet confirm this) along with SwaggerHub and a few other options.
A good API goes beyond just the payload definition and I’ll walk through the other considerations and explain why these other areas are important.
An extract of our new book Implementing API Platform has been made available by the publishers Packt here. Of course you could enjoy all the content by buying the book directly from Packt (go here) or from book retails such as Amazon (here).
After months of labour, the arrival of new family members for a couple of the authors the Implementing Oracle API Platform Cloud Service book as finally been published. The book has been included into Packt’s Expert series so, earns(?) the privilege of having photos of the authors on the cover. The book can be purchased directly from Packt (go here) or from book retails such as Amazon (here).
It has been an interesting experience. Whilst working as part of a team of four authors lightened the writing load, a lot more energy went into communication so things were lined up. If you want a challenge, why not read the book and try to work out who wrote which chapters!
Now the big news, we have just agreed with Packt Publishing to write a book around Oracle’s new API Platform Cloud Service (APIP CS). This is going to be more of a team effort with 4 of us working on the book. With all the authors working for Capgemini as well it should be a lot easier in terms of effort The book is being targeted for late this year to be published so that we can cover the major features being released this summer which will make the product a lot more rounded and complete.
The book will also bring in another initiative that has been running in a fairly low profile manner, but starting to shape up in the form of something called OMESA (OMESA.io). This initiative is a cross party approach to define a reusable reference architecture that engages both the legacy landscape along with API driven / microservices based contemporary solution delivery.