Tag Archives: apiary

APIs more than a payload spec – Examples of Good APIs

31 Sunday Oct 2021

Posted by in APIs & microservices, General, Technology

≈ 1 Comment

Tags

, , , , , , , , , , , , , ,

I recently presented at APIWorld about how API definitions go beyond the payload specification into providing details of terms and conditions and so on. You can see the presentation here (more about my presentations here).

One of the questions during the presentation did I have other examples of good APIs, reflecting the points I’d made. A very valid question, to which I didn’t have more examples to hand, hence this post.

So the easy answer would be to point to an excellent article on Nordic APIs (here) that address the question and explain why they rate the APIs. But that’s a little bit of a lazy answer and in all fairness, the examples provided are from organisations where APIs are recognised as a primary or important contributor to business revenue. So I’ve looked at areas where the API may not necessarily be seen by the business as the primary source of revenue. With the examples provided, we’ve described what we think is good, or not so good about them. Hopefully, through these examples, you’ll see why points are made in the presentation. So here are my reviews…

Continue reading →

UKOUG Conference 2018

04 Tuesday Dec 2018

Posted by in API Platform CS, APIs & microservices, General, OIC - ICS, Oracle, Technology

≈ Leave a comment

Tags

, , , , , ,

With the start of December comes the UK Oracle User Group conference, or to be more precise the Independent UKOUG.  This year the conference is back in Blackpool, a slightly smaller venue than the ICC in Birmingham, but in many respects that made the event feel more vibrant and busy.

The user group also announced some of the changes it is making going forwards reflecting the changing needs of its members – SIGs being largely superseded by multi-stream single day events (Summits) with the Call for Papers for the first of these here.  A wider list of Oracle related Calls for Papers is available here.

Of course being a UKOUG Volunteer, I have been presenting and co-presenting.  The slides from my presentation sessions can be found at:

This was an abridged version of the an update on my presentation here 

My second presentation was a review of Oracle Integration Cloud, in which I presented some customer use cases of OCI  as part of a wider presentation on OIC by Sid Joshi. 

This was followed on the second day with two API based sessions, the first being a deep dive into custom API Policies on the Oracle API Platform.

The final session, was another short one looking at Apiary which was primarily a demo of what the solution can do.

On top of trying to keep up with my usual workload – a very hectic couple of days.

Oracle Developer Meetup London – September 2018

18 Tuesday Sep 2018

Posted by in APIs & microservices, Dev Meetup, General, Technology

≈ Leave a comment

Tags

, , , , , , , , , ,

#OracleDevMeetup in London - GraphQL

Last night we ran the latest of the Oracle Developer Meetups in London. This time Luis Weir presented on GraphQL, which got an very engaged discussion about the strengths and weaknesses of GraphQL, in-depth points about how the error paths should be handled among many other things.

The presentation material Luis used is based upon his Devoxx session earlier this year and can be seen here:

The links to Luis’ examples can be found on his GitHub account – https://github.com/luisw19/graphql-samples

After a insightful and thought provoking presentation on GraphQL the Drones with APIs project had its latest update.  Providing a lot of laughter to the evening’s proceedings. Including demonstration of flying the drone using REST APIs published via a gateway and Go back-end.  This included the DroneDash presenting a visual presentation of the commands being issues via REST, as seen here:

All the code, API definitions and documentation for people to add or extend can be found in the meetup’s GITHub – https://github.com/oracledeveloperslondon/.

A few of the useful links used or mentioned last night are:

 

The next meetup is planned for Monday November 19th.  Topics  will be published soon.

 

#OracleDevMeetup in London - GraphQL

API Design

05 Monday Feb 2018

Posted by in Books, General, mindmap, API Platform CS, APIs & microservices

≈ Leave a comment

Tags

, , , ,

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.

Designing Great Web APIsSo 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:

great APIs

You can also access my MapWise view here. James’ book can be obtained freely from O’Reilly here.

The book doesn’t go into the depth of details for practises that Apiary (Pro Edition) offers with style guidelines which will describe morec detailed recommended practises (more here).

1st London Oracle Developer Meetup

20 Wednesday Dec 2017

Posted by in APIs & microservices, General, Oracle, Technology

≈ Leave a comment

Tags

, , , , , , ,

Meetup Dec 17-1Monday night (18th December) I co-hosted with Luis Weir the first London OracleDeveloperMeetup. Despite being a Monday evening in the run up to Christmas where a lot of people will attending Christmas events, needing to finish present shopping or event started their holiday we still had a tremendous turn out. With nearly 50 people out of almost 100 registrations coming to the Oracle London Office.

The evening kicked off just after 6pm with beer, pizza and time for people to Network. At 7pm we started with what had been scheduled to be two short 25 minute presentations to share insights into API design best practices and an overview of Apiary. Such was the interest,  interaction and conversation in the subject and content that the session over ran. But here in lies one the benefits of a Meetup over things like conferences. In the Meetup the is space and time for the presenters to adjust to what the attendees wish to cover rather than beholden to the venue scheduling.

Picture1With the presentation and discussions finding a suitable pause, it was an opportunity for a  call to arms to be made, and for people to try using developing APIs. With a mission defined which we hope people will try to continue with as it will contribute to the next Meetup. You don’t need to have attended last night’s event to participate in the next Meetup. If you want see what we’re going to try achieve take a look at the end of the slide deck. We think it will be be very entertaining and the source of a lot of laughter and amusement.

Some people did take up the challenge, others took it as an opportunity to talk further about the technology or just network.

We have now setup a GitHub so that people can contribute to the development of the API ready for the next event (https://github.com/oracledeveloperslondon/droneAPI­).

If you would like to see what is being tweeted about the event checkout #OracleDeveloperMeetup on twitter.

Photos can be seen here.

We hope you will join our Meetup and register for the event when we announce the final details. In the mean time give Apiary a try, share with us the API you have designed.

The slides are here:

 

ODC Appreciation Day : Apiary Editor

10 Tuesday Oct 2017

Posted by in General, Oracle, Technology

≈ Leave a comment

Tags

, , , , , ,

This post is my contribution to the Oracle Developer Community (ODC) Appreciation Day. The idea of the event is best explained by Oracle Base – go here.

The Apiary Editor has to count as a pretty new entry into the possible features that could be considered with Apiary only coming into the Oracle family in the last year. Apiary as a solution provides a platform by which modern REST based APIs can be designed, documented and simulated. Apiary supports the API First design philosophy (more here) using API Blueprint notation or Swagger (now known as Open API).

The feature I want to focus on is the Apiary Editor itself (shown below), particularly when working with the API Blueprint.  The beauty of the solution is that as the documentation or API syntax is edited in the editing side (left)  the API definition/documentation immediately appears on the presentation side of the editor  (right) making it easy both see the technical specificastion and how the information is initially presented to a potential API user. This makes it really easy to understand the clarity of what is being communicated which is one of the important aspects of an API definition and API first.

Whilst Agile development states ‘prefer working code over documentation’ this provides agility as you can develop the API definition and allow people to develop against the contract we can still easily deliver quality API descriptions with sufficient information to make it understandable to a 3rd party.

Challenges for the Citizen Integrator

02 Saturday Apr 2016

Posted by in General, Oracle, Technology

≈ Leave a comment

Tags

, , , , , , , , , , , , , ,

cloudgs_integrationWe’ve been developing the example integrations to go with book on ICS and have encountered some interesting challenges for the Citizen Integrator (CI) when using an iPaaS (integration Platform as a Service). To say it in non techno speak  someone wanting to plumb system together without needing to be equipped and have the skills of a developer and just using the cloud. One such example is SOAP API testing, before connecting live systems together even a CI will probably want to check that you have mapped the data correctly – important when you’ve potentially got functions and repeating structures in the mapping. To go back to my old analogy that tools for a CI like ICS are the same as Excel to ERP. Then like when creating formulas in a spreadsheet you’re going to plumb in some numbers and check the formula’s results before using in anger.boomerang2b1366

So far so obvious, the fun comes not when you’re wanting to simulate the source event coming into the tool – this can be done through a raft of utilities from Chrome Browser extensions such as Boomerang, soapui_logoSoapUI for example. Things become a lot more challenging when   comes when you want the integration output to go to a mock SOAP API.   The choices available are limited, and pretty much come down to:

  • If you’re lucky you might be able to connect to a test instance of the target service. SalesForce offers a sandbox instance for example to those with a production instance of SalesForce.
  • However sandbox/test instances are less likely for ‘in house’ solutions or products offered as an on premise solution unless there happens to be active development on the solution taking place.screenshot_48
  • Ideally a mocking tool is the route to go – but only 1 option in this space appears to be available for SOAP called mockable.io
  • Other than mockable you’re into using locally installed software and things get messy as it means getting the outbound web traffic routed to your own machine and then use something like MockServer (there is a great article about this tool by my book co-author Robert van Molken here). The chances are unless the network & security manager(s) are good friends or you like messing with your home network it isn’t going to happen.
  • The final option is instantiating an IaaS platform such as Amazon (AWS Free Developer intro scheme to keep your cost down) or perhaps Oracle IaaS, although I’d suggest this is a fairly expensive route to enable the testing of an integration, not to mention the effort to setup things to run the test.

With REST services things are somewhat easier, as there is a lot more tools geared to helping the design of APIs, testing them and critically providing a proxy based framework 65f3fc0eadfae8135439b4ff48f63fd4to enable monetisation. For example Apiary.io can create a test harness for you. Others such as Apigee, also offer such abilities. Apiary offers a trial account and we’ll be hearing a lot more about Apiary in the near future. There is a possible work around, which is to create test integrations that  map the SOAP content into a REST service (Apigee offers such a capability) but with certain constraints you could also do this within ICS itself. But we’ll look at such options within the book (can’t go without to money shot 😀 ).

This of course has only looked at the conventional use of SOAP, if you need to work with a SOAP interface that makes use of the more advanced WS-* extensions such as Reliable Messaging then things come pretty serious, and I’m afraid today you’re going to need to resort to development, and I suspect you’ll not escape that in the future either.