Documenting APIs on the Oracle API Platform

Tags

, , , , ,

The last week or two I have been working on a new API Platform utility to add to my existing tools (see here). This tool addresses the question of generating documentation.  Much as been said about API documentation and the quality of it, check out these articles :

If you look at these articles and others, there are some common themes, which are:

  • Document the URI / payload
  • Describe error handling
  • Describe contracts such as how many API calls
  • How the API is authenticated

Apiary covers the first theme to a first class standard,  and you will see Apiary called out for its ability to document APIs in a lot of articles. Well written API Blueprints will cover the bulk of the second bullet. But the other points tend to fall outside of a Blueprint and fit more the API Policies and their use.

Not everyone is so commited or enjoys writing documentation. The other driver for going beyond the use of Apiary is that some organizations feel the need to have a traditional word style document to capture/define an API’s contract in detail. With the API Platform the management portal enables an API to be published into the developer portal with the Apiary definition and a markdown file for further documentation.

Continue reading

Praise for Microservice Patterns

Tags

, , ,

richardson-mp-meap-hiI’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.

microservicepatternlanguage

Microservices are not simple

Tags

, , , , ,

It’s a bit controversial to say ‘Microservices are not simple’ given much is said about using Microservices to simplify and accelerate software delivery. So, how can this statement be made? It is a point actually stated in Chris Richardson’s excellent new book Microservice Patterns (avalable here and here), indirectly in Eric Evan’s Domain Driven Design (here). Martin Fowler in one his blogs says that they come at a premium (here). So, I’m not the first to say this, and wont be the last.

But the assertion that Microservices done right are simpler, and allow rapid delivery and evolution of solutions – a bit of a contradiction. As they say a picture is worth a thousand words, so take a look at this …

Continue reading

UKOUG Tech 18 Conference

Tags

, , , ,

The call for papers for the U.K. Oracle User Group’s 2018 Conference in December is out. The committee are looking for papers across not just core Oracle technologies like the database and SOA Suite but newer technologies such as Event Hub. With Oracle’s engagement with developers and the commitment to open source the UKOUG has moved to engage with these users as well. So the committee will welcome submissions about open source tech that maybe run on an Oracle platform. You can submit your proposals here.

If you’re considering making a submission but want some advise or suggestions then reachout to the UKOUG and its committee members – contact details are here.

Terch18

We look forward to seeing you in Liverpool in December.

Lessons in Oracle Cloud Password Management

Tags

, , , , ,

Oracle Cloud is growing and maturing at a tremendous rate if the breadth of PaaS capabilities is any indication.  However, there are a few gotchas out there, that can cause some headaches if they get you. These typically relate to processes that impact across different functional areas. A common middleware stack (API CS, SOA CS, OIC etc) will look something like the following:

cloudPassword

As the diagram shows when you build the cloud services, the layers get configured with credentials to the lower layers needed (although Oracle have in the pipeline the Oracle managed version of many services where this is probably going to be hidden from us). Continue reading

Oracle Dev Meetup

Tags

, , , , , ,

Another month and another Meetup.  Last night was the quietest session we’ve had. But then we covered Identity Management and whilst the subject is so important it isn’t too popular.

Tanks to Atul Kumar for taking on the task of presenting on this subject.  You can find out more about Atul at:

The content covering use of Messaging Cloud and our drone project can be seen here:

Domain Driven Design

Tags

, , ,

I have been wading through Eric Evan’s Domain Driven Design Book. As with many design and architecture focussed books I try to mindmap as I go so I have a quick reference resource. The mindmap for this book can be seen below and is linked to the WiseMap version which is dynamic.

In terms of of a review of the book, it contains lots of nuggets of helpful ideas and information but it is a rather heavy going to read. Some points feel over laboured such as the use of consistent language, at times it feels like half the book is dedicated to this one point. Whilst Chapter 14 – Maintaining Model Integrity sounds unadventurous as a chapter, I found this to have a lot of really helpful content such as going into the details Bounded Contexts and so on which is highly relevant to the world of microservices.

design book.png

Successful PaaS Team

Tags

, , , , ,

39919340285_bde0aacde1_zLast week we attended the Oracle EMEA PaaS Forum in Budapest. I have to say we’re proud to be part of a team that has picked up two conference awards.  Firstly our CTO Luis Weir for Contributions to API Solutions and then the wider team have collected an award for overall Outstanding PaaS Contributions.

40823835111_5b00f7963e_z

L-R, me, Amy Grange, Soham Dasgupta (Capgemini Netherlands), Luis Weir (Oracle Delivery Unit CTO), Jurijs (Yury) Fjodorovs

Some photos from the trip can be found a here.

London Oracle Developer Meetup No. 2

Tags

, , , , , , ,

Last night was the 2nd London Oracle Developer meetup with 100 people registered and  CTO Luis Weir presented on 3rd generation APIs which included their relationship to microservices. The outcomes was not only a excellently delivered presentation with an enaged audience, but led to some really thought provoking discussions, particuarly on the application of microservices in financial  contexts.  For example is it possible for for financial institutions to get near the post child Netflix in terms of building and delivering solutions to production given the certification and compliance requirements? Some interesting insights on PSD2 (Payments Service Directive 2)  as well.  Are questions like is a monolith wrong?

Screenshot 2018-03-06 14.27.26In addition to the high level architectural debate the evening included a shortened walk through on the possibilities of deploying the API Gateway and its relative ease compared to other products.

Finally we concluded with an update on the project that we’re running as an underlying theme for some of the meetups – that of using variuous tech to command the drone(s) via a set pf published APIs.  This included a call to arms to contribute eith to building your own apps to use the API or contribute to the back end as the solution gets built using an API  1st approach.

The slides from the event.

Resources: