API Design Governance – Style Guides in Apiary

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”

ICS to API Platform

I’ve been using the API Platform and Integration Cloud Service (ICS) for some time now.  Independently, they are powerful products but together they are even better.

Initially, most ICS use cases were SaaS to SaaS or an extension to an existing SaaS.  But more and more I’m seeing people use ICS in place of a standard service bus to do basic validation, enrichment, transformation and routing.

But how do you expose these ICS services using standard API methods?  Well, it isn’t too difficult to go into API Platform and define an API to point to the ICS service, but this could be quite tedious.

Luckily, all the Oracle products have an “API first” strategy, so it wasn’t too difficult to setup an ICS flow to automatically publish new services into the API Platform.

Continue reading “ICS to API Platform”