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.
Continue reading “API Design Governance – Style Guides in Apiary”
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
- Testing APIs.
- Understand API Analytics, consumption, metrics and monitoring dashboards.
Continue reading “Teaching How to Design and Secure an API with Oracle API Platform”
Season 3 of the Developer Experience Workshops had just kicked off today in Perth. And travelling to Melbourne tomorrow for the meetup tomorrow night and then the workshop after that.
See what is happening at the upcoming workshop here at medium.com.
Here are the upcoming workshop (at the point of publishing this article):
Melbourne – Wednesday 8 Nov 1800 Meetup – (York Butter Factory) – http://bit.ly/2hJgfBk
Melbourne – Thursday 9 Nov 0900 Official Session – (Oracle Office ) – http://bit.ly/2zgifsj
Brisbane – Tuesday 14 Nov 0900 Official Session – (Oracle Office) – http://bit.ly/2lUVHtV
Brisbane – Tuesday 14 Nov 1800 Meetup – (Oracle Office) – http://bit.ly/2AlQBKr
Wellington – Monday 20 Nov 1800 Meetup – (TBD) – To Be Finalised
Wellington – Tuesday 21 Nov 0900 Official Session – (Oracle Office) – http://bit.ly/2AbnXuD
Auckland – Wednesday 22 Nov 1800 Meetup – (TBD) – To Be Finalised
Auckland – Thursday 23 Nov 0900 Official Session – (Oracle Office) – http://bit.ly/2hee2k7
Sydney – Wednesday 29 Nov 1500 Official Session – (Oracle Office) – http://bit.ly/2hg3pxx
Adelaide – Thursday 30 Nov 1500 Official Session – (Oracle Office) – http://bit.ly/2h6kQg0
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.
Continue reading “A New Hackathon Experience”
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.
Read More Here to read about what happened.