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!
I’ve been reading Chris Richardson’s new book Mixroservice Patterns published by Manning (here or here). Whilst I haven’t finished the book yet, I have read enough to feel I can provide worthwhile observation.
The book is supported by Chris’ website microservices.io which provides the patterns and related content in summarised form – great for a memory jogger and quick reference, but doesn’t make a substitute for the book.
When it comes to the book, Chris’ writing is extremly engaging whilst economic with its language – no long passages when a short sentence can convey everything necessary (unlike this one for example 🙂 ). For example, in three short paragraphs is an explination as to why there is a tendancy for IT people to point at particular technologies or techniques as silver bullets. As a result is incredibly informative and points to sources that inform the thinking – such references can be as diverse as Sam Newman’s Building Microservices to the (real) architect Christopher Alexander and Jonathan Haidt (The Righteous Mind).
The book is grounded in honest real world thinking being upfront and clearly pointing to when Microservices aren’t the right answer, to talking about the difficulties that can be expected in working with microservices. This won’t surprise anyone who has heard Chris speaking (here for example).
A recommended read.
Oracle’s API Platform (API-P) product avoids the use of external configuration management. If you want to better understand why, then checkout our forthcoming book as it goes into detail about why this is the case (it can be pre-release version of the book can be obtained here). In a previous blog I wrote about and illustrated the use of the API-P’s own APIs so that it was possible to see what API iterations had been deployed to API Gateways.
In this blog I want to explore the issues of version management a bit further. API-P provides internal version management through the idea of iterations as previously explored (Understanding API Deployment State on API Platform). In addition to this there are API policy attributes called version, status etc. This information whilst having some impact on behavior reflects the version of the ‘contract’ that the API represents between the consumer and provider, and requires a manual change.
The API policies themselves are version tracked through the iteration identifiers. Each time a policy is saved the iteration is is incremented. What the API-P doesn’t support is the concept of branching. In relatively simple API Policy branching is unlikely to ever be an issue.
Why is a reversion capability needed?
Let’s take a more complex scenario. In our book API Platform we introduced the some APIs that would allow the retrieval of meta data about artists in the record companies’ catalog. It has however come to light that the API has been targeted with malicious calls, firstly through trying to attack using injection attacks and secondly trying to overload the back end by creating data requests that make the back-end work hard in retrieving data.
To defend against this, the API Policy has been enhanced to include some custom groovy policies to inspect the values provided. Strictly speaking following the principles of Semantic Versioning the API version should go from 1.0.0 to 1.0.1. However seeing that the ‘contract’ as presented to the consumer hasn’t really changed – the data models are the same, the URI goes unaltered resulting in the implementation team not changing the version.
During development processes, it is not unusual to be developing existing logic, and decide that approach being used isn’t right or not going to perform as well. So you abandon your changes and revert back to the last approved version. However, this isn’t possible as any save will result in a new iteration. The API-P will be getting some enhanced version management features. But today to be able to undo the changes we need a means to ‘revert forward‘ (hence the tool name) that is to take an older iteration and make it the latest, as illustrated in the next diagram.
Today the API-P doesn’t provide a means to perform this process within the User interface. However when looking at a gateway you can review the API policy deployed. As we established previously that you may have different gateways deployed with different iterations. Given this, as API-P has been built true to the principles of separating the UI from the backend through the use of APIs we can deduce there should be a means to get the details of an API with a specific iteration.
To this end we have built on the pattern previously illustrated to provide the means to ‘Revert Forward’ by creating a Groovy script that will use the APIs provided by API-P to retreive an iteration and push it back at the latest version. When the policy is pushed back it also modifies the description to show which iteration has been pushed.
You may ask, why not use the conventional developer approach of branching as suggested in the following diagram. However API-P’s iteration framework doesn’t extend to support this.
The next with this is pretty predictable – how do I know which iteration to revert to. You have two options here, firstly either revert in order so you can see the prior version in turn – which whilst visually good, is not necessarily the most practical option. So in the tool we have a parameter that will allow you to display on the console the configuration of each iteration. This does mean you are going to see the policies in a JSON presentation. To make life easier we would recommend good practise and recording in the policy description information that helps determine the policy’s characteristics – and this can be used to better determine iteration behaviour.
If we are able to take an earlier iteration and make it the latest one by pushing it back then it is a short step to actually target a different management cloud in effect migrating the policies. Whilst possible it comes with some serious cautions …
- You risk undermining your version management, which management cloud has the master, and the iteration numbers will NOT migrate so it’s not like this info can be used to distinguish the laster version
- The logic included doesn’t accommodate handling differences in policy versions – so if trying move between instances of the API Platform they need to be the same version otherwise your configuration could make a mess of thing
- This issue is further compounded if you are deploying custom Java policies.
- Environment specific policies simply won’t work for example gateway based routing.
Oracle does not recommend that the policies be stored anywhere outside of the platform, whilst it this utility makes that a possibility, it deliberately avoids writing any of the information to the file, the policies only reside outside of the platform for the duration of the process execution.
The Tools Commands
All the parameters assume the values will not contain any space characters. Each command is preceded by a dash eg. revertForward.groovy -inpassword mypass -inSvr https://a.b.com
- -h or -help – provides this information
- -inName – user name to access the source management cloud
- -inPass – password for the source management cloud
- -inSvr – The server address without any attributes e.g. https://22.214.171.124
- -policy – numeric identifier for the policy of interest
- -iter – iteration number of interest for the policy – optional
- -outName – optional, the target management cloud username, only needed for migrations
- -outPass – optional, the target management cloud password, only needed for migrations
- -outSvr – optional, the target management cloud server address – same formatting as inSvr, only needed for migrations
- -override – optional, if migrating to another management, tells the script to replace the existing policy of the same name if found
- -view – optional, separate command to allow viewing of the policy – requires one of the following values:
- display – displays all the details of the policy, if no iteration is provided this will be the latest iteration
- summary – provides the headline information of the policy including name, change date etc
- summary-all – summarizes all the iterations from the current one back to the 1st
- -debug – optional, will get script to report more information about what is happening
The code can be obtained from my GitHub repository here.
When it comes to ensuring I keep up good practises, I try to look at books in areas I think I have a good handle on such as APIs. Why? well it confirms and validates I’m upto date; sometimes another view point can spark ideas on how to make something better, improve an approach or simply understand another way of explaining an idea. The later is important as the key benefit of knowing something is the opportunity to help someone else. Not everyone communicates or understands ideas in the same so this is always helpful.
So recently I ran through James Higginbotham’s Designing Great Web API’s book(let). Often when goping through a book I mindmap it so that I can share it, and refer to it as a lit of prompts reminders if necessary. Whilst’s James’ book doesnt reveal anything new or relevatory for anyone working with APIs it does provide a good succinct explination to basic practises. So here is the mindmap:
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.
We will of course continue to blog about ICS at https://oracle-integration.cloud
Recently I’ve given some time over to catching up on some reading. Which has included Walter Isaacson’s tremendous book Innovators. I picked this up more because I liked Walter’s approach to the Steve Job’s biography. I thought this was going to be more focused on individuals and how they brought through new technology innovations. But actually it is a very good potted history of the development of modern computing. Whilst I work in IT and thought I knew key contributors, from Babbage, Lovelace to von Neumann and Turing. I was rather surprised at how many signficiant contributors I didnt know, or only vaguely aware of. For example the work of Douglas Engelbart who pretty much lead the design for the mouse. What about Vint Cerf who made key contributions to TCP/IP? Stephen Crocker who was responsible for the RFC that we all associate with the IETF now?
Not only is the history interesting, the book looks at the dynamics of innovation and how much innovation comes from the individuals working away on their own and having a eureka moment compared to that constant dialogue between people which sounding off each other lead to new ideas? The later is beautifully illustrated with the development of the transistor and the work of John Baarden and Walter Brattain. It’s interesting that as the history moves into the pre-internet era that more and more of advancements are a result of collective effort, but also recognised as such. I wonder whether that is because technologies made collaboration easier, or the effects of socio-cultural developments that meant people recognised the collaborative efforts?
I’d recommend this book to anyone who is interested in IT has developed or even just interested in the interplay of personalities and events such as World war II that influenced scientific advancement.
When I read a technical book from cover to cover I usually build a mind map so that I can use it as a memory jogger in the future if I need to return to get key points such as arguments or facts. With the ferstive break I have had time to finish reading Sam Newman’s Building Microservices. The following is a static image, but clicking on it can take you the dynamic site provided through WiseMapping, it does take a moment or two as the map is large (or click here).
Many of the points made in this excellent book are true to software design and development generally, but given a Microservices spin. For example, monitoring and security should be incorporated into any good design.