Category Archives: tools

Development Standards for API Policies?

16 Monday Dec 2019

Posted by in API Platform CS, General, tools

≈ Leave a comment

Tags

, , , , , , ,

When it comes to development, we have had coding standards for almost as long as we have been coding. We tend to look at coding standards for purposes of helping to promote good quality code and reduce the likelihood of bugs and so on. But they also help with readability, making it easy to navigate a code base and so on. This is sufficiently important that there is a vast choice of tools to help us ensure we align with good practices.

That readability etc, when it comes to code interfaces lends to making it easier to use an interface as it promotes consistency and as Don Norman would say avoids ‘cognitive load‘, in other words, the effort involved in performing actions with the interface. Any Java Developer will tell you, want to print out an object (any object) you get a string representation using the .toString() method and direct it using the io packages.

That consistency and predictability are important not just for code if you look at any API best practises documents you’ll encounter directly or indirectly the need to use conventions that drive consistency – use of singular or plural for the name of entities, application of case – camel case, snake case etc. Good naming etc and we’ll see related things appear together in the documentation. Products such as Apiary and SwaggerHub include tooling to help police this in our API design work.

But what about policies that we use to define how an API Gateway handles the receipt and routing of API invocations? Well yes, we should have standards here as well. Some might say, governance gone mad. But gateways are often shared services, so making it easy to see and logically group APIs together at very least by using a good naming convention will help as a minimum. If API management is being administered in a more DevOps fashion, then information security professionals will probably want assurance that developers are applying policies in a recommended manner.

Continue reading →

Notifications from Oracle API Platform Cloud Service

11 Monday Nov 2019

Posted by in API Platform CS, General, Oracle, Technology, tools

≈ 2 Comments

Tags

, , , , , , , , , ,

There are circumstances in which notifications from the Oracle API Platform CS could be seen as desirable.  For example, if you wish to ensure that the developers are defining good APIs and not accidentally implementing APIs that hit the OWASP Top 10 for APIs. Then you will probably configure things such that developer users can design the APIs, configure the policies, but only request an API to be deployed.

However, presently notifications through mechanisms such as email or via collaboration platforms such as Slack aren’t available.  But implementing a solution isn’t difficult.  For the rest of this blog we’ll explore how this might be implemented, complete with a Slack implementation.

Continue reading →

Making Scripts Work with IDCS Deployed PaaS

09 Saturday Feb 2019

Posted by in API Platform CS, APIs & microservices, General, Oracle, Technology, tools

≈ 5 Comments

Tags

, , , , , ,

A while back I made some utilities I developed to help with managing the API Platform. At the time we didn’t have access to an IDCS based environment, so credentials worked using basic auth (I.e. user name and password). But with environments managed by IDCS tokens are used.

As a developer with a Java background I have to admit to liking Groovy over Python for scripting, not to mention for the API Platform groovy is part of the gateway deployment and SDK. Meaning it is readily available in its 2.x form (3.x is relatively recent and aligning to the latest Java idioms). We haven’t tested against Groovy 3.0

Thank you to Andy Knight for sharing with us some Java code which I adapted to be pure Groovy (removing external dependencies for processing JSON). The result is a script that can be taken can be taken and worked into other scripts (which is what we have done for our previously provided scripts – Understanding API Deployment State on API Platform, Managing API Policy Versioning in Oracle API Platform, Documenting APIs on the Oracle API Platform). But this script can be used to get a token and display it on the command line or write it to file. Writing tokens to files is generally not good practise, but as a temporary measure when working on developing scripts arguably a managed risk.

The script can be found at https://github.com/mp3monster/API-Platform-Utils/tree/master/getToken and all the details on using the script can be obtained by passing -h as a parameter. The important thing is to understand how to obtain the Client ID and Client Secret, the details of which are described at https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/find-your-client-id-and-client-secret.html

Analytics and Stats for APIs

05 Friday Oct 2018

Posted by in API Platform CS, General, Oracle, Technology, tools

≈ 3 Comments

Tags

, , , , , , , ,

NOTE:This utility needs revamping to support IDCS for more see Making Scripts Work with IDCS Deployed PaaS

The Oracle API Platform provides the means to examine statistics and slice and dice the numbers by application, gateway, duration and so on resulting in visually appealing graphical representations.  The way the analytics works means you can book mark specific views, so you can return the same report view with the relevant features as often as you like.  However, presently there is no data export option.

The question why would I want to export the information comes down to several possible use cases, all of which relate to cost management.  The API Platform will eventually have all the desired data views, but now something to help address the following:

  • money-tization, we can see which consumer has been using the services by how much and then send the data to a companies accounting systems to invoice the users
  • Ability to examine demand and workload over time to create a projection of the likely infrastructure – to achieve this the API statistics need to be overlaid with infrastructure and performance details so we can extrapolate API growth against server workload.

To address these kinds of requirements, we have taken advantage of the fact the API Platform has drunk its own Champagne as they say and made many of the analytics querying APIs publicly available.  As with the other API Platform tools, the logic has been written in Groovy, and freely available for use – we’ve covered the code through a Create Common license.

Tool includes a range of parameters to allow the data retrieved into a CSV file having filtered in a number of different ways – which logical gateways to examine, which API or Application(s) to report on.  Finally, just to help some basic stats are produced with a count of logical gateways, API calls, APIs defined and Application definitions. The first three factors inform your cloud costs. Together the stats can help Oracle understand your use case. Note that the parameters which impact the CSV generation can also materially impact the reporting numbers.

Parameters:

The 1st three values must always be provided and in the order shown here

  1. user name to access the source management cloud
  2. password for the source management cloud
  3. The server address without any attributes e.g. https://1.2.3.4

All the following values are optional

  • -h or -help – provides this information
  • -g – Logical gateway to retrieve numbers from e.g. production or development. using ALL with this parameter will result in ALL gateways being examined
  • -f – the file to target the CSV data should be written to. If not set then the default of
  • -t – indicates whether the data provided should be taken from an APPS perspective or from an API view by passing either APPS | API
  • -d – will get script to report more information about what is happening
  • -p – reporting period which is defined by a number as follows:
    • 0 – Last 365 days – data is given as per month
    • 1 – Last 30 days – this is the default if no information is provided – data is given as per day
    • 2 – Last 7 days – data is given as per day
    • 3 – Last day – data is given as per hour

NB – still testing the utility at this moment – will remove this comment once happy

Documenting APIs on the Oracle API Platform

21 Monday May 2018

Posted by in API Platform CS, General, Oracle, Technology, tools

≈ 2 Comments

Tags

, , , , , 

Updated reflecting changes discussed in blog post:
Making Scripts Work with IDCS Deployed PaaS

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 →

Understanding API Deployment State on API Platform

25 Thursday Jan 2018

Posted by in API Platform CS, APIs & microservices, development, General, Oracle, Technology, tools

≈ 6 Comments

Tags

, , , , , , , , ,

The new Oracle API Platform makes it possible to deploy different versions of your APIs to different gateway instances. When you you’re managing the Development API Policies through all the different stages of the lifecycle (Design to Production) from a single management tier such a capability is essential. This is further challenged by the fact that each save of you API Definition creates a new iteration (the term used to identify each saved ‘version’ of the API)

However it does lead the challenge from a management perspective of knowing which iterations are running on each Gateway.. you can get the information from the current UI but it requires multiple steps to get the information. The UI also lends itself more to the design processes today than perhaps the more dense information views that a operational report might warrant.

I’m sure that over time these views will come, but today we can solve the problem by taking advantage of the fact that the product lives by its own ‘mission’ by offering a very rich set of APIs. As a result it becomes possible to actually build your own views. To that end I have written a Groovy script which will go through each API that can be seen and retrieves the iteration deployed to each logical gateway.

In terms of running the script you obviously need Groovy installed. It expects 3 parameters which are:

  • Server address e.g. https://1.2.3.4
  • Username e.g. weblogic
  • Password e.g. Welcome1

You can hardwire into the script default values which will then be used if no parameters are provided.

Here is a screenshot of some output.  I have masked out some information for reasons of security. But there should be enough here to give a sense of what is happening:

APIPlatformScript

The script includes suppressing certificate validation – necessary if you haven’t yet deployed your own specific certificate and still working with the default Oracle certificate.

Feel free to take the script and play with it. I make no claims to it’s elegance etc but I have tried to comment it so you can see what is going on. I have tried to keep the code fairly simple so you can see how it works and processes the JSON responses. The script is available at: https://github.com/mp3monster/Utils/blob/master/getDeployedIterations.groovy

For more about the APIs involved in the script, checkout