In closing out 2020 and before going on leave, I was given an opportunity (never a challenge). And it came in the form of these Oracle Code Cards. For those that haven’t seen them, this is what they look like and here is a git repository of some code explaining more about the cards themselves that I’m revamping – https://github.com/jlowe000/codecard.
The outcome required was as open as I could get.
There were no boundaries and there were no specific rules.
Last weekend saw over 2,000 people participate in the #DigitalDefence Hackathon hosted by Hackmakers, Oracle as the lead sponsor plus a vast range of other sponsors – ITIC, AustCyber, NASSCOM CoE, Cyber Security Centre of Excellence, IBM and community partners – Public Sector Network, Slack, Black Nova Group, Yirigaa, UNSW DataSoc, SLASSCOM, DataCated Academy and DataEthics4all.
This event was off the back on #BuildWithAI Hackathon hosted by Hackmakers. Being a contributor to that event as a Lead Mentor, Sponsor and a Challenge Organiser, there was something there that resulted from what we were able to deliver – another step in the infinite game. (Note – I haven’t read the book, I don’t follow Simon Sinek however from different communities and framework where we focus on growth mindsets, long tail and talking about your why – this is another example of that same conversation).
Much has been written on the design of ideal REST APIs, from Roy Fielding’s original description of HATEOAS interfaces, to much more practical approaches mirroring APIs rolled out by large technology companies. When working alone, I have a lot of freedom in how I design and build my APIs, and I always strive to design APIs which I would love to consume, based upon a number of undocumented, but strongly-held design intuitions. Collections are plurals; sub-objects are used sparingly, and mostly for practical considerations like payload size; HTTP status codes are used appropriately for particular types of errors and responses; etc.
When I work as part of a larger team, I often find that we end up building interfaces with slight inconsistencies, even if the design of them was based upon some documented high-level design principles. These inconsistencies impact the productivity of both internal and external developers which have to use these APIs, as they have to carefully parse the documentation to develop around the ‘quirks’ of the individual APIs.
Ironing out these inconsistencies can be achieved in a couple of ways, adopting a waterfall-style development model, in which each team is required to submit their detailed design specifications to an architecture council for review and sign-off; or putting a system in place which checks new API designs for consistency, and provides real-time feedback to API designers as they sketch out the interface. Oddly enough, the approach that I am going to discuss in this blog post is not the former; instead we are going to explore the Style Guide capabilities offered by Apiary.io, which allows us to develop rules governing API styles, which are assessed in real-time during API design.
This blog is the second part of an end-to-end exercise that starts explaining the steps to clone a GitHub repository that contains an agnostic Medical Records application, built by us in NodeJS and which exposes REST API endpoints via a Swagger API-descriptor running locally on Swagger UI (all included as part of the repository). The previous part of this 2-blogs series also explains the steps required to run the MedRec NodeJS application on Docker containers either locally or in the Oracle Public Cloud. For more information about this first part, go here.
Moving to this second part, we are going to cover the following steps:
Create an Apiary account used to Design APIs (API First approach) and create a new API Project using the existing MedRec Swagger API-definition.
We are going to spend a little bit of time playing with Apiary to feel comfortable in areas such as:
Validating API definitions
Testing API endpoints
Switching across out-of-the-box Mock Servers and real Production MedRec service end-points.
Login to Oracle API Platform and configure an API, this includes:
Enforcing Security and other policies.
Deploy API and securing access level to on-premise and Cloud-based API Gateways.
Publishing APIs into the API Developers Portal.
Linking API to Apiary Swagger API-definition living document.
Login to API Developers Portal (API Catalog)
Register a New Application
Understanding the role of API Keys
Reviewing MedRec API Documentation
Registering to consume MedRec APIs
Understand API Analytics, consumption, metrics and monitoring dashboards.
APIs are becoming the window to the digital assets of the modern business. Well documented, well governed and easy to use APIs are key to their successful uptake, longevity and associated business success. Yes, I did say well documented. In this instance I am talking about the documentation required to describe the APIs capabilities in a manner that is meaningful for your ultimate audience, the “API Consumers”, however it will also provide the template for the API Developer to develop their code from. In the modern business climate, we probably don’t want to produce War and Peace, we simply want to take a minimum viable approach to our API documentation. But where would I find a capability that will simplify our task as API Designers, capture the design documentation for our APIs, allow us to do some initialise testing to validate the usefulness of our design before any code is cut, and also have the documentation ready for consumption by team members and interested parties using a standards based approach. Where indeed ! Look no further than Apiary.io. Continue reading “Apiary designed APIs tested using Dredd”
This week I was attending a customer event. It was an interesting learning experience on different levels. It was a great opportunity to meet some people that I would not normally would be.
It was a hackathon put on by MLC Life Insurance (#MLCLifeHackathon) and we (as Oracle) were happy to support them as one of their partners. I’ve been to other hackathon events but they were organised differently. So I was curious to see what their objectives were. It would too easy to be cynical. With an open mind, I was happy to be part of their journey.
Last week I had the opportunity to pop into QUT Foundry and attend an event called Designing Products For Adaptability, Innovation & Sustainability. It was a great experience and there were lots to learn about it. The guest speakers included Prof. Tyson Browning from TCU visiting from Texas and Dr. Rafael Gomez from QUT. It was an opportunity that I embraced to meet new people and be part of a growing community.