# Ricky Moorhouse: technical writing
> The full text of the technical posts and projects on https://rickymoorhouse.uk/, newest first. See https://rickymoorhouse.uk/llms.txt for an overview of the whole site.
---
# Rookery, an experimental AI blog
URL: https://rickymoorhouse.uk/blog/2026/rookery-an-experimental-ai-blog/
Date: 2026-11-14
Tags: ai, api
A month ago, I started an experiment - Rook: an AI agent with its own blog, [The Rookery](https://rookery.api.me.uk), about APIs and AI. Unlike this blog where the writing is all mine, the Rookery is an experiment in an agent researching and drafting posts with me reviewing for publication. Here's how it works and what I've learned so far.
This is all on [github](https://github.com/rickymoorhouse/rookery) so you can see for yourself and take a look at [the blog](https://rookery.api.me.uk) as well.
- Every Monday, Rook reviews stats from previous posts, chooses an idea from a list of potential ones, researches it and drafts a post for Thursday.
- Rook has a guide to the voice in which to write posts and respond to comments, maintains its own list of ideas - striking through the ones that have been completed and adding to the list from the research.
- Rook sends a pull request to me for review and will make changes based on my comments and suggestions. An example of this was my suggesting the inclusion of OpenLint examples in the latest post. Once I'm happy I merge the post so it can be posted on the scheduled day.
- Comments on the posts are handled using [utterances](https://utteranc.es) through github comments - Rook reviews the comments and proposes replies which I can approve before posting.
- On Thursday the scheduled post is published to the blog and announced through [Rook's Bluesky account](https://bsky.app/profile/rookerybot.bsky.social).
So far there are 5 posts on the blog and I like how it's starting out. I'm interested to see how the topics develop and the voice holds up across the posts. I really like how Rook started with [Every Agent is an API Client](https://rookery.api.me.uk/posts/every-agent-is-an-api-client/) and the latest on [good descriptions](https://rookery.api.me.uk/posts/api-descriptions-that-stand-alone/). Have a read and let Rook know what you think in the comments!
---
# Adding SocialSpec to my site
URL: https://rickymoorhouse.uk/blog/2026/adding-socialspec-to-my-site/
Date: 2026-10-18
Tags: blog, socialspec, hugo
On Tuesday, Caleb Hailey [announced](https://calebhailey.com/links/socialspec/) [SocialSpec](https://socialspec.org) around the premise that the future of social media is websites. This maps out a consistent way to expose key social data (about, contact, following) from your website based around existing standards and ways things are typically done already. This makes it very easy to adopt and add to an existing website - for me this meant the following:
## Start with a feed
I'd previously ended up with my feeds available at multiple URLs so this was an opportunity to clean things up. Rather than just copying what I had to the feed.xml and feed.json locations and add more complexity, I decided to make these the definitive sources for my feed and redirected the old URLs to them through edge rules. To get [Hugo](https://gohugo.io) to create an RSS feed in another location to the default index.xml (which I'd never liked), I created a custom output format [for RSS](https://github.com/rickymoorhouse/blog/blob/main/themes/2026/layouts/home.feedxml.xml) and referenced this in the config. I already had a custom output format for jsonfeed as Hugo doesn't have that built in. My custom output references my adapted rss.xml, but you could just point to the built-in one. The config.yaml looks like this:
```yaml
outputFormats:
feedxml:
mediaType: "application/rss+xml"
baseName: "feed"
rel: "alternate"
noUgly: true
feedjson:
mediaType: "application/feed+json"
baseName: "feed"
rel: "alternate"
isPlainText: true
outputs:
home: ["HTML", "FEEDXML", "FEEDJSON"]
```
## About Page - [aboutspec.org](https://aboutspec.org)
I updated my blog build process to copy my markdown about page into the .well-known folder:
```sh
cp public/about/index.md public/.well-known/about.md
```
## Contact Me - [contactspec.org](https://contactspec.org)
I exported a vCard (.vcf) and updated it to just have the values I wanted to share. I then dropped this in my static/.well-known/ folder and updated my CDN settings in Bunny to serve it as text/vcard based on the file extension. This works as an Edge Rule where if the RequestURL matches *.vcf, then it sets a response header.
## Following - [followspec.org](https://followspec.org)
Initially I was just going to export an OPML file from [NetNewsWire](https://netnewswire.com/), but I decided to create a [data file](https://github.com/rickymoorhouse/blog/blob/main/data/blogroll.yaml) for the blog so Hugo would generate both an OPML file to put in .well-known as well as an HTML [blogroll](https://rickymoorhouse.uk/blogroll) which will hopefully make both easier to update going forward. Again this needed a CDN update for the content type to text/x-opml.
## Testing this
After adding these I explored testing them through [HyperTexting](https://hypertexting.com/), Caleb's social news feed based on the existing connections across the open web - an ungated social network. As this didn't work I built my own [test tool](https://rickymoorhouse.uk/socialspec) with Claude to validate what I had set up against the spec. After contacting Caleb, it [turned out](https://socialspec.org/news/hypertexting/#fn:1) the version available at the time wasn't yet using the full spec but rather an earlier iteration - but on the TestFlight version of the update it worked perfectly. For now I have added a temporary edge rule to redirect the hypertexting specific URLs.
This is early days for the spec but looks to be a good way to make social connections more open.
---
# API failure stories and what they taught me
URL: https://rickymoorhouse.uk/blog/2026/api-failure-stories-and-what-they-taught-me/
Date: 2026-10-06
Tags: api
API failures often come from missing lifecycle controls rather than difficult technology. These generalised stories from my experience show how unchecked assumptions around versioning, testing, logging, and access control can create avoidable problems.
## When API versions stop making sense
Imagine an API with versions like these:
`v1`, `v1-updated`, `v2`, `v2-legacy`, `v3-final`, `v3-final-final`
The problem isn't that multiple versions exist. Supporting multiple versions in parallel is a common, deliberate and reasonable decision. The problem here is missing lifecycle controls to define how versions would be created and retired - each time the API was changed the versioning approach had to be reinvented alongside the change. This results in no one knowing:
- which versions are in use
- which consumers are using which ones
- which versions can be safely retired
- what would break if one of them was turned off.
This also made consumer-reported issues harder to diagnose: before debugging could begin, the team first had to establish which API version the consumer was using.
Up front you need to define a [versioning](/blog/2026/api-versioning-is-a-contract-commitment-not-a-technical-choice/) and deprecation strategy - it needs to cover how breaking changes are identified, how long older ones remain supported and how consumers will migrate. [Structured usage data](/blog/2026/observability-as-a-design-requirement/) is also essential as you need to know which consumers are still actively using a version before you can safely retire it.
## A migration without reusable tests
A migration was planned - same software but a different environment and with it new network routing. The migration itself was straightforward, but the lack of reusable tests made it a lengthy manual comparison exercise. This consisted of calling each API in turn with curl on the new and old environments, then painstakingly comparing the responses and headers - each subtle difference discussed and examined - will this cause a problem anywhere?
The migration exposed differences in how network paths and forwarding headers were handled. Some consumers behaved differently in the new environment as the pre-cutover manual testing didn't cover every consumer behaviour.
Testing needs to be considered an ongoing exercise and even if you find yourself coming up to a change without tests, building them for re-use based on the existing traffic rather than as a one-off migration exercise will bring benefits. AI tooling can assist with comparisons generating initial tests and sample calls, but the resulting tests still need to be reviewed against the contract and the intended behaviour and maintained over time.
## Sensitive data in the wrong places
Operational reviews can surface sensitive data in places it shouldn’t be. The discovery then triggers an incident response process, which then has to establish how the data had arrived, where else it had been stored, and how it could be removed. This then can lead to identifying other places where sensitive data wasn't being handled as intended in the implementation.
Solving this properly is something that needs to start in your API design - make sure you have a good understanding of all the sensitive data your APIs will be touching and how it will be handled. Then build up a layered approach to protect it:
- API design: sensitive data should never be logged in plaintext, so shouldn't appear in the query string - if needed for a query then do this through a POST body but make sure you have no logging of body content.
- Redaction: configure redaction policies for fields containing sensitive data to keep them out of logs
- Log levels: ensure the logging levels you have don't log request and response body
- Environmental configurations: sometimes you may need to see how data is handled in dev, but restrict when it goes to UAT or preprod - apply this at the environment level.
Any per API setting needs to be checked in your pipeline and used as a gate - then your development debugging never accidentally makes it to production. For a deeper look at implementing these controls in API Connect, see [Securing Sensitive Payload Logging in API Connect](/blog/2026/securing-sensitive-payload-logging-in-api-connect/).
## Authenticated does not mean authorised
This first came to me in a quiet conversation - "I think we found a bug in the portal", but turned out to be a misconfiguration based on false assumptions. The portal used OIDC-based SSO through an identity provider that allowed self-registration. Authentication was working, but no authorisation controls had been configured - once you were in you could see, subscribe and call any API - they were effectively public to anyone who could self-register with the provider.
Fortunately in this instance, no one had exploited the misconfiguration before it was caught and corrected.
Whilst some APIs may have been intended for a wide public audience, the majority weren't. The solution here is granular controls ensuring you control who can discover the API exists (visibility) and who can subscribe to it (subscribability). For APIs that need more control, make use of explicit approval flows so access to the individual API becomes the control point. The key thing to remember here is that we need both authentication (who someone is) and authorisation (what they may do).
---
In each case, the technology was capable of doing the right thing. The problem was that an assumption had not been turned into a documented rule, an automated test, or an enforced control.
Next time, before releasing or changing an API, ask:
- Do we know how breaking changes will be versioned and deprecated?
- Do we know which consumers use each version?
- Can we repeat the tests that validate the API’s expected behaviour?
- Have we identified sensitive data and prevented it from reaching logs or query strings?
- Have we verified we have both authentication and authorisation configured appropriately?
- Are these expectations enforced in the delivery pipeline rather than just relying on people remembering?
---
# GitOps Deployment of API Connect
URL: https://rickymoorhouse.uk/blog/2026/gitops-deployment-of-api-connect/
Date: 2026-07-25
Tags: apiconnect
As architect for the API Connect Cloud offerings one of the key areas I am involved in is deployment and in particular deployment automation. With my SRE background the main goal here is that anything we need to do more than once should be automated - deployment being a big one of these. Across our cloud environments - single-tenant and multi-tenant, IBM Cloud, AWS and Azure from dev through to production we probably have over 80 deployments of API Connect. These all use automation to deploy from declarative deployment models - in particular GitOps so our git repo is the source of truth for everything that gets deployed.
This is split into two primary areas - deployment of cloud services dependencies (Kubernetes clusters, object storage set up etc. ) and the application deployment itself.
## Infrastructure - Terraform
For the cloud service deployments we use Terraform so we can declaratively describe the infrastructure requirements and have clean separation between the base template and the per environment configuration (region, size, ha-requirements) through variables. This all lives in git.
## Application - ArgoCD
For everything that goes into kubernetes we use ArgoCD - which means all of the manifests for deployment live in our git repos and are watched by ArgoCD for changes. These are structured making use of ArgoCD's SyncWaves so that they are deployed in the right order and we know that the dependencies are in place before moving on. For example:
- -200 - Pre-requisites (cert-manager & issuers)
- -100 - Monitoring tooling
- 300 - API Connect CRDs and operators
- 400 - Management subsystem
- 500 - Analytics subsystem
- 600 - Developer portal
- 700 - Gateways
Just like in the old days of basic we've used multiples of 100 to allow us to add things in between later without reshuffling everything! In ArgoCD the default syncwave for anything without one specified is zero - so using negative waves for pre-reqs means we don't have to annotate all the CRDs and if we miss anything we know the pre-reqs are already there. In the manifests this would look like:
```yaml
metadata:
annotations:
argocd.argoproj.io/sync-wave: "100"
```
This is a simplified overview, in our SaaS environments we add additional cloud specific components that handle tenant provisioning and ui based configuration addons which have their own waves in the deployments. We follow a similar pattern with the manifests that we do with the terraform - a base template and environment specific configuration. In this case we have used kustomize & helm based charts in different places as they both have distinct benefits for different use cases.
**Use Kustomize** when environments have significant differences. It uses a base template and overlays, making it much easier to follow what is actually happening compared to complex Helm syntax.
**Use Helm** when environments are identical except for minor elements (like hostnames). It uses values files to pass variables into charts, making it perfect for simple toggles (e.g., dev vs. prod).
In a repo the difference looks like this:
#### Kustomize
```text
bases/
management/
management_cr.yaml
kustomization.yaml
gateway/
gateway_cr.yaml
kustomization.yaml
overlays/
dev/
kustomization.yaml
management-patch.yaml
gateway-patch.yaml
prod/
kustomization.yaml
management-patch.yaml
gateway-patch.yaml
```
#### Helm
```text
Chart.yaml
values.yaml
values-dev.yaml
values-prod.yaml
templates/
management_cr.yaml
gateway_cr.yaml
```
With Kustomize the `bases/management/management_cr.yaml` holds the common shape of the `ManagementCluster` CR and `overlays/dev/management-patch.yaml` only contains the fields that differ for that environment (endpoint hostnames, [profiles](https://www.ibm.com/docs/en/api-connect/software/12.1.1?topic=profiles-component-cpu-limits-memory-limits-licensing), feature enablement). The patch only carries the fields that differ for this environment:
```yaml
# overlays/prod/management-patch.yaml
apiVersion: management.apiconnect.ibm.com/v1beta1
kind: ManagementCluster
metadata:
name: management
namespace: apic-prod
spec:
profile: n3xc4.m16
endpoints:
management: mgmt.prod.example.com
```
The `overlays/dev/kustomization.yaml` then pulls it all together:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../bases/management
- ../../bases/gateway
patchesStrategicMerge:
- management-patch.yaml
- gateway-patch.yaml
```
With Helm the same effect comes from templating the differing fields in `templates/management_cr.yaml` and overriding them per environment in the values file:
```yaml
# values-prod.yaml
management:
profile: n3xc4.m16
endpoints:
management: mgmt.prod.example.com
```
We use Helm for our multi-tenant SaaS environments where the regional deployments need to be the same and Kustomize for single tenant deployments where we need to support more per-tenant differences.
## Secrets
Everything that is not sensitive lives in the git repo - the secrets are then injected into the charts at deploy time from the relevant secrets manager for the cloud provider. These are abstract primarily through the use of [ArgoCD Vault Plugin](https://argocd-vault-plugin.readthedocs.io/en/stable/) which supports a number of different secret backends.
This means our secret manifests have references rather than the actual secrets. For example the `Secret` we mount for the Management subsystem's DB credentials in prod looks like this:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mgmt-admin-pass
namespace: apic
type: Opaque
stringData:
password:
```
At sync time ArgoCD Vault Plugin resolves each `` reference against the configured secret backend (IBM Cloud Secrets Manager, HashiCorp Vault, AWS Secrets Manager etc.) and rewrites the manifest with the literal values before it is applied to the cluster - the rendered manifest never lands in git, and the cluster ends up with a standard `Secret` that the operator can consume.
For customer owned secrets we've [integrated](https://www.ibm.com/docs/en/api-connect/cloud/12.1.1_saas?topic=domain-managing-external-secrets-datapower-nano-gateway) [External Secrets Operator](https://external-secrets.io/latest/) to provide a similar abstraction at runtime.
---
# Everything as code
URL: https://rickymoorhouse.uk/blog/2026/everything-as-code/
Date: 2026-07-19
Tags: apiconnect, gitops, iac
A valuable technique I've found is treating everything I can as code - checked in, reviewed, and versioned. This post covers what that looks like across infrastructure, deployments, APIs, and even documentation, and why the discipline matters more than any specific tool.

## What does "as code" mean?
By 'as code' I mean storing as a version controlled source of truth in a declarative form. This is distinct from building custom code as an automation in that what is being stored represents the desired state, not the steps to get there.
## What can be treated as code?
- **Infrastructure**: defining the infrastructure components and configuration through a declarative language to be used with a tool such as [Terraform](https://www.hashicorp.com/en/products/terraform) to deploy and maintain state.
- **Application deployments**: for deployments to Kubernetes, you can use YAML manifests in a repository and then [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) will keep the cluster in sync with what you have defined.
- **API definitions**: Store your OpenAPI specifications and gateway policy definitions in version control and use the API Connect toolkit to publish them to your gateway and developer portal - [example with GitHub Actions](https://github.com/rickymoorhouse/api-automation/blob/main/.github/workflows/deploy-api.yaml). [API Studio](https://www.ibm.com/docs/en/api-connect/cloud/12.1.1_saas?topic=studio-managing-api-projects-in-vcs) also makes it easy to work directly with your git repo.
- **Governance rulesets**: See also [Git is your governance source of truth](https://apievangelist.com/2026/06/30/git-is-your-governance-source-of-truth/)
- **Process documentation & runbooks**: Storing your documentation and runbooks as [markdown](https://daringfireball.net/projects/markdown/) in a repo gives you that built in change history and management rather than having to remember to update the changelog manually in the front of a word document.
- **Diagrams**: If you make use of a text based diagramming tool such as [Mermaid](https://mermaid.ai/), you can get these same benefits for your architecture diagrams making it easier to see over time how things have changed. Whilst you could also store [draw.io diagrams](https://www.drawio.com) in git and follow the changes, it is slightly less clear with its XML-based format.
## Advantages
- Traceability — you know who made which changes.
- Currency — you know when it was last updated.
- Time travel — git history lets you revisit any prior state.
- Repeatable and Consistent — you can always instantiate from the declarative source
- Peer review via PRs — there is a built in system for proposing and reviewing changes
- Drift detection — you can see when your system diverges from the source
## How this works in practice
This model is fundamental to how my team at IBM works. All our internal documentation and runbooks live as markdown files in git repos. For our cloud deployments the infrastructure is defined in Terraform, all the manifests are stored in git and deployed with ArgoCD. Having this consistency and repeatability is essential when you're maintaining over 80 stacks. We deploy a set of our own APIs to every stack using the toolkit. My next post will cover more detail on our deployments.
## Pitfalls to watch
Whilst treating everything as code has its advantages there are a number of things to watch out for. You need to make sure you have a way to handle sensitive data separately and ideally scanning to avoid these being unintentionally leaked through your version control system.
Not all data types work well in a system designed around text files, for example large or binary data that you can't easily compare changes in. This will balloon the repo size and start to make things painful for everyone using it.
The review process can become tedious if not handled carefully - it needs to be thought through so that you get the benefit of peer review without it becoming a checkbox or a blocker.
## Conclusion
The value in treating everything as code really comes from the mindset and the discipline around it, which is much more powerful than any specific tool. If you adopt this approach you get a common set of consistent practices across many different artifacts: traceability, review and a way to revert changes. In my next post I'll dig into how this is done in our API Connect cloud deployments.
---
# Machine-readable?
URL: https://rickymoorhouse.uk/blog/2026/machine-readability/
Date: 2026-06-28
I've always been interested in ensuring my blog was readable to humans and machines - so over the years I've added and experimented with different ways to do this as what it means to be machine readable has changed. I currently have a range of these supported from embedded metadata to alternate versions that can be used with an LLM. Currently on this blog I am using the following:
- [RSS](https://www.rssboard.org/rss-specification) Feed - [my RSS feed](/feed)
- [JSON Feed](https://www.jsonfeed.org) ([validator](https://validator.jsonfeed.org))- [my json feed](/jsonfeed)
- [hentry](microformats.org/wiki/h-entry) ([validator](https://indiewebify.me/validate-h-entry/))
- [TechArticle](https://schema.org/TechArticle) ([validator](https://validator.schema.org))
- [OpenGraph](https://ogp.me) ([validator](https://opengraph.dev))
- Alternate markdown version - [this page in markdown](../machine-readability/index.md)
- [standard.site](https://standard.site) ([validator](https://site-validator.fly.dev/))
As I recently added the alternate markdown version and the standard.site integration here's some details on how:
## Adding standard.site to my hugo static blog
Initially I started using [Sequoia](https://sequoia.pub/) which is a great tool that can handle processing and posting documents from a static site and whilst it did a great job of processing and posting my content, I wanted a bit more control. In particular the way I handle featured images didn't fit with its model and I didn't want to inject links into the generated html - I wanted this as part of the main templates. Adding the [meta tags](https://github.com/rickymoorhouse/blog/blob/bb1f993d07cddc80ec0d344848fe46e90d057ee4/themes/2026/layouts/_partials/header.html#L13-L16) to the template was straight forward - always including the publication reference and the document one where specified in the frontmatter.
Now the next thing to do was to find a new way to post the documents and obtain the `did` for the standard.site document. I came across this [useful guide](https://piccalil.li/blog/publishing-on-the-atmosphere-with-standardsite/) which gave me some good pointers on the basics through nodejs examples, but as I prefer to write scripts in python, I ported the ideas into my own script. Whilst building this I used [pds.ls](https://pds.ls) to check on the [results](https://pds.ls/at://did:plc:r53zv4vpzeihop3aliwyejlu/site.standard.document/3mpdm5lzbzl2f).

You can see my [current script in github](https://github.com/rickymoorhouse/blog/blob/main/scripts/atmosphere.py) - this will either take in an md file as a parameter or identify one from the staged commit. The script then builds the standard.site.document lexicon content:
```python
document_record = {
'$type': 'site.standard.document',
'site': blog_did,
'title': post_data['frontmatter'].get('title', 'Untitled'),
'publishedAt': post_data['frontmatter'].get('date'),
'textContent': text_content,
'canonicalUrl': post_url,
'contributor': {
'did': agent.me.did,
'role': 'author',
'displayName': "Ricky Moorhouse",
}
}
# If there is a featured image, upload as blob and get the reference
if 'featured' in post_data['frontmatter']:
featured_image = post_data['frontmatter']['featured']
# get relative path to the post file, removing the file name
post_path = post.rsplit('/', 1)[0]
# Upload to atmosphere and get the blob reference
blob_ref = upload_featured_image(agent, post_path, featured_image)
document_record['cover'] = blob_ref
```
If I have an atUri already in the front-matter, the existing document is updated, otherwise a new one is published and adds the atUri to the front-matter. At the moment my workflow is to write the post, stage the commit and then run the script before updating the commit and pushing to GitHub where my actions will then publish the blog post, but eventually I plan to move the script to be run from the actions as part of the publishing. I'm also experimenting with using an LLM to generate a post for social media to link to the article.
## Markdown versions of posts
As well as extending to push documents to atproto using the standard.site lexicon I've added markdown files for easier consumption by AI Agents - inspired by [isitagentready](https://isitagentready.com/). These files are generated through hugo as part of the publishing flow.
To add markdown versions of posts, I just added markdown as an output format, created .md versions of my page and home template and included metadata pointing to the `alternate` version in the header - you can see how in this [commit](https://github.com/rickymoorhouse/blog/commit/f09280ff7edee0bedf90ee09cd489d6c2852cc89).
Once the files were being generated, I added a Bunny CDN Edge rule to handle content negotiation so that if content type of `text/markdown` is requested, then I redirect to the md file. This way the same URL can be used for reference and humans and agents will each get the most appropriate version.

---
# MCP Ponderings
URL: https://rickymoorhouse.uk/blog/2026/mcp-ponderings/
Date: 2026-06-21
Tags: ai, mcp
Agents are only as good as the access they have to accurate data and business functions. LLMs have a cut off point as to what they know - they're trained on a set of data and anything beyond that is unknown to them - therefore to build useful agents you need to provide a way for them to access data beyond that corpus. This could be more your own business data or just more recent information. To enable this Anthropic [introduced Model Context Protocol][anthropic-blog] (MCP) as an open standard to build these connections to data-sources and tooling. Since then, MCP has exploded into the most common way of providing tools to AI Agents.

There are 2 main types of MCP Server - **local** which you download and run on your machine (just like a CLI tool) and **remote** that you connect to through a URL (just like an API). They can both be configured and they both have their risks - so we need to consider how we safely manage these in our environment, building on how we control and manage APIs and software and APIs.
## Local MCP Servers (stdio)
There are thousands of pre-built MCP servers out there to download and use - some official but mostly unofficial community built servers created by interested developers or their AI Agents. According to [Equixly] 43% of MCP servers contain command injection flaws and 30% permit unrestricted URL fetching, so it is important to understand what you are running. This highlights the fact that traditional security practices still apply to the agentic space - often more than ever. Supply chain security and least privilege are more critical than ever when you have non-deterministic agent flows handling data through community tooling.
Often these are documented with a single command to download and run that you add to your agent config - using `npx` or `uvx`, however you can usually still download, build and run in the traditional way you would opensource projects to ensure you stick to the version you have verified. This way you have a level of control over the tools you are using but would still need to be sure to keep dependencies up to date.
## Remote MCP Servers (streamable-http / sse)
In a lot of ways use of a remote MCP server is very similar to using a third-party API as part of your application, in fact some places I've seen MCP tools provided where there wasn't previously even an API or access to the MCP be made easier than it was previously to get access to the API. There are however some key differences:
As Agents connect to MCP servers they will initialise a session and list the tools available with their specifications dynamically as a kind of discovery each session which is loaded into the agent context. The ensures they always have the latest tool definitions, can adapt accordingly and don't need to review a separate spec or changelog if the tooling is updated.
As they are being used in a non-deterministic process, you don't know up front what your agent will be sending them. For example agents build the tool call based on their language model, your input and the tool specification without formal object declarations, so it is all open to interpretation which may lead to unexpected sequences of tools or needing to retry to get parameter formats correct. Whilst APIs would typically define input types using json schema, MCP defines tools with textual descriptions. One example I've seen was with timestamp formats where the backend the tool interacted with was expecting ISO8601 format but the agent was trying to use relative times.
## Security checklist for MCP
Ultimately, the responsibility for the security and integrity of these systems remains entirely with the user. Because agentic flows are non-deterministic the risk of an unintended action, triggered by a flawed community tool or a prompt injection, is higher than in traditional software.
- **Audit** the tooling - whether this is the source code downloaded or the provider of the hosted server - before you connect you should ensure you can trust it with your data.
- **Isolate** downloaded tools to limit the risk of command injection, for example running the MCP server within a Docker container controlling what they can access. For remote MCP servers, routing calls through a gateway gives similar control to restrict, observe and adjust interactions as needed.
- **Credentials** - Use dedicated credentials for MCP tooling that can be revoked, and apply the principle of least-privilege so they only have permissions they need.
- **Approvals** - Ensure that sensitive actions require a human approval.
- **Review** that the tools continue to work as you intended them to.
Also see [API Evangelist: MCP discovery and governance](https://apievangelist.com/2026/06/19/mcp-discovery-and-governance/)
[Equixly]: https://equixly.com/blog/2025/03/29/mcp-server-new-security-nightmare/
[anthropic-blog]: https://www.anthropic.com/news/model-context-protocol
---
# Securing Sensitive Payload Logging in API Connect
URL: https://rickymoorhouse.uk/blog/2026/securing-sensitive-payload-logging-in-api-connect/
Date: 2026-05-22
Tags: apiconnect, security
Unintentionally logging sensitive customer data (PII, financial info) is a major compliance risk. When deploying APIs, ensuring that this data is kept out of your logs requires robust, layered controls. Whilst developing APIs that will deal with this sensitive content you will often need to see what is being passed to ensure that everything is being handled as expected. Very often in a development or test environment you will be using a dummy payload to ensure the API is working as expected so it is key to ensure it is reflected at the different stages of processing as part of your test suites.
When you progress to partner integration testing with an API you are no longer as in control of the payload passed in through the client, so at this point become dependent on payload logging to see what is being passed and processed. At this point as we would still be dealing with dummy data this would be acceptable in most cases.
Once the API use progresses towards production and real sensitive data is being transferred you need safeguards in place to ensure the data is no longer being logged. Of course data security requires a layered approach and this article only covers one area of this - payload controls. This needs to be paired with additional strong security controls such as ensuring there is encryption in transit and at rest across your system and sensitive data isn't being transmitted in the query string which could be logged by other network components ([owasp ref](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url)).
In API Connect there are several features that can be used to assist with this and the combination to use will be different depending on your specific requirements. Depending on your goal will determine which one is most appropriate in your scenario:
- To see the data in lower environments to assist in development, make use of full payload activity logging
- Protect specific fields in logs using redaction policies
- Ensure compliance standards are met across the board make use of Governance Rulesets
- To prevent any logging of certain data globally, make use of analytics Filters
Let's examine each of these features in turn:
## Activity Log settings
The default behaviour in API Connect is to log activity for all APIs and only log payload (request and response body) on error - but this can be customised on a per-API basis. For the DataPower API Gateway, this is configured in the [activity-log](https://www.ibm.com/docs/en/api-connect/cloud/12.1.0?topic=policies-activity-log) extension and the options are payload, activity, headers or none and in the yaml it looks something like this:
```yaml
activity-log:
success-content: headers
error-content: headers
enabled: true
```
This could also be configured to reference Catalog properties so that you make these settings at a catalog level and all the APIs reference this with syntax like `$(catalog-error-content)` in your api definition.
## Redaction policy for field level controls
If you don't want to restrict the entire body of the API and it is specific known fields that contain sensitive data, you can use the redaction policy to remove or replace these fields with asterisks. The policy uses JSONata to identify the fields to modify. For this you need to first use the log policy in gather-only mode in order to modify the logging. The `gather-only` mode in the log policy is crucial because it instructs the policy to collect the full, sensitive payload and place it into the internal log context object. This allows the subsequent redact policy to operate on the logging data itself, prior to it being written to analytics, ensuring the client receives an unmodified response while the sensitive data is masked in the logs.
```yaml
- log:
title: Gather log to redact
version: 2.0.0
mode: gather-only
- redact:
version: 2.0.0
title: redact birthday in the logged data
redactions:
- action: redact
path: $.**.birthday"
root: log.response_body
```
Whilst this can also be used to remove or redact the full body it is more typically used on individual fields as adding a policy to each API when you can just set the activity log level is mostly overkill.
## Governance rulesets to check
Whichever approach you take, you can make use of governance rulesets to ensure that all APIs meet your standards - these can be used in a CI CD pipeline for checking the status before publish or even configured on a catalog to block publish if the rules aren't met. Governance within API Connect supports the use of spectral rulesets to scan API specifications at development time, through CI/CD pipelines and in periodic catalog scans.
```yaml
extends: spectral:oas
rules:
# Ensure activity-log.success-content is header
activity-log-success-content-header:
description: "activity-log.success-content must be set to 'header'"
message: "activity-log.success-content must be 'header'"
severity: error
given: $.x-ibm-configuration.activity-log
then:
field: success-content
function: pattern
functionOptions:
match: "^header$"
# Ensure activity-log.error-content is header
activity-log-error-content-header:
description: "activity-log.error-content must be set to 'header'"
message: "activity-log.error-content must be 'header'"
severity: error
given: $.x-ibm-configuration.activity-log
then:
field: error-content
function: pattern
functionOptions:
match: "^header$"
```
## Analytics filters
If you need to ensure these are never logged in the whole API Connect deployment you can set up filters in the Analytics Cluster configuration. There are two settings here one for storage and one for offload.
```yaml
spec:
...
ingestion:
...
filter: |
mutate {
remove_field => ["response_body"]
}
```
Navigating payload security in API Connect is not about choosing one feature; it's about implementing a defense-in-depth strategy. Start with foundational security (encryption in transit and at rest). Then, apply appropriate Activity Log configuration to get appropriate visibility at each stage. Where you need more fine-grained control, use Redaction Policies to target specific fields.
To continuously validate your configurations meet your compliance requirements make use of governance rulesets in CI/CD and finally, use Analytics Filters as a system-wide preventative guardrail. By stacking these tools appropriately you move from merely tracking data to actively securing it throughout its entire lifecycle.
---
# API Versioning is a Contract Commitment, not a Technical Choice
URL: https://rickymoorhouse.uk/blog/2026/api-versioning-is-a-contract-commitment-not-a-technical-choice/
Date: 2026-04-13
Tags: API, versioning, architecture
Teams spend a lot of energy arguing about whether to put the version in the URL, a header, or a query parameter. That debate usually misses the point. The real question is: what is your change management discipline, and how do you protect consumers from breaking changes?

Taking a step up from the versioning question - how are you managing changes to your API contract? Ideally this would be transparent to consumers unless there is something they are looking to take advantage of in the new changes. If your API is designed well it can abstract any internal requirements and technical limitations from your clients such that you can update the implementation internally and their applications will continue to operate without even needing to know about it.
So a versioning strategy really comes back to what sort of changes you are expecting to your API. As with most things having an understanding of what you will do in this space up front is going to make things smoother down the line.
- **Externally versioned standards** (e.g. FHIR, OpenAPI specs tied to a standard) — your hands are largely tied. Both you and your consumers need to track versions explicitly, and you'll likely need to support multiple versions in parallel during transitions.
- **Additive changes** (new fields, new endpoints) — these can often be transparent to consumers, as long as clients are told upfront to ignore unknown fields. No formal versioning strategy may be needed.
- **Breaking changes** (removing fields, restructuring data types) — you need an explicit consumer-facing versioning strategy.
You'll still need to pick an approach so here's how the main methods compare:
- **URL Path** (`/v1/`) - very common and highly visible approach, but maintaining a separate set of endpoints for every version.
- **Header-based** - keeps URLs clean, but no standard and complicates caching.
- **Query Parameters** - sitting somewhere between the two above - easy to see what is going on without multiplying endpoints for each version.
- **Gateway Managed** - instead of client specified versioning you can handle this provider side through an API Gateway, routing consumers to the version of the API they are subscribed to.
No matter which way you choose to handle changes to an API you need to start from your strategy around how you intend to handle changes to your APIs. This needs to be an upfront plan and integrated into your API Contract commitments to your clients rather than something you leave until you need it. Once you have a clear strategy and have committed to it, you can handle technical requirements within that framework much more easily.
When none of these options feel right or you see that breaking changes are frequent and the versioning overhead is getting in the way it may be time to look at GraphQL where you let the client determine the data they are requesting rather than dictating the content from the provider side.
---
# Observability as a design requirement
URL: https://rickymoorhouse.uk/blog/2026/observability-as-a-design-requirement/
Date: 2026-03-28
Tags: architecture, api
## What can you actually see in your API platform?
To go from an API working for the developer building it to knowing it is working for your consumers is where API observability is key and can give you the confidence in the decisions you made building it.
I once made the mistake of turning off logging of metrics for one of our APIs and only discovered this when we needed to debug an issue, at which point we were blind to what was happening with it. As well as having a strategy for observability, it's important to check it is working as expected!

## What do your error responses tell the consumer?
The API Consumer needs visibility too, not the same view as those running the platform but enough to figure out if their calls are successful and when they're not why. Status codes and error responses are the primary way to do this and providing something clear and actionable makes it a lot easier for consumers to self-resolve issues.
Beyond the API response itself it is also key to give them a way to see how their applications are calling the API once they are deployed and probably can't see the response directly. This is often through the developer portal so they can easily find out how their applications are using the APIs alongside the documentation and credential management.
Clear actionable responses and observability is even more crucial when the consumer is an AI agent. An agent won't infer what's going on from an obscure error code and outdated documentation. It will retry and seek to workaround the problem likely in ways you didn't intend. For agent consumers, having clear and actionable errors are the difference between recovering gracefully and getting stuck in a runaway loop.
## Correlation and trace propagation as contract commitments
If you're committed to providing this traceability of requests to your API, why not include the appropriate headers in your OpenAPI specification as part of the contract. This makes it clear for the consumer this is something the API provides you rather than there being mysterious extra headers on requests that you don't know if you can rely on to use. If it makes sense to and is possible then supporting propagation of trace headers from inbound requests makes sense - in multi-region distributed systems these can be really valuable in understanding what is happening.
## Designing for debuggability, not just availability
As you build out your API architecture, ask yourself: "how will I know what is happening here?" If you can answer that at design time, you'll have it covered when you need it in production.
The time to think about what you'd need to debug a problem is when you're designing the system — not at 3am when you're already in the middle of a failure.
A consistent, unique request ID propagated through all your logs and traces is one of the simplest things you can do. When something goes wrong, being able to follow a single transaction end-to-end across your system is invaluable.
---
Observability isn't something that you bolt on after your API is live - it is worth thinking through as you design your system. A well thought out strategy here will save you and your consumers time in production.
---
# Designing for Multi-Region API Deployments
URL: https://rickymoorhouse.uk/blog/2026/designing-for-multi-region-api-deployments/
Date: 2026-03-14
Tags: architecture, api
The requirement to be multi-region usually comes suddenly, an immediate business demand, a compliance deadline, or the aftermath of an incident. When designing API Connect SaaS, the decision was to build each region completely independently. Within a region it's highly available across availability zones, but the regions themselves don't replicate. The reasoning is straightforward: as a shared API management platform serving customers with fundamentally different requirements - data residency, cross-region resilience, or both - independent regions let each customer build the topology that fits their constraints, rather than the platform prescribing one.

## What is your requirement anyway?
The first thing to consider when designing a multi-region API deployment is to make sure you are clear on what the fundamental business requirement is that is driving you towards a multi-region strategy. There are a number of routes that lead towards multi-region planning and they will all drive different variations to the design.
- **Latency** - ensuring your APIs respond quickly from the regions you have consumers calling them
- **Resilience** - providing a failover for if there are issues in one region.
- **Compliance** - ensuring data and/or traffic to remain in a particular region
For improved latency across regions - is this required primarily around read APIs or do you need to handle write operations as well? If it is primarily reads, then you may be able to reduce your latency with the use of a CDN with edge caching without the complexity and cost of a full multi-region deployment.
If you're looking for resilience, will your requirements be satisfied with a primary region that normally will handle everything and a secondary location that can pick things up if the primary is down or do you need them both to be able to handle traffic in parallel? How long can you cope with a failover between regions taking - seconds or hours? These are the factors that will drive how you go about implementing a multi-region solution.
## An API is only as good as its data
Whilst it is relatively easy to replicate API Gateways and application servers between regions - this only gets you so far, as at the end of the day the API depends on a data source. Where does the data for your API reside - what requirements for data storage need to be factored into the overall architecture?
If you have an API that is read-heavy and the data is not time critical you may be able to use replication with eventual consistency saving on the performance hit, cost and complexity of ensuring strong consistency between replicas.
If you have a write heavy API - how will you handle conflicts between writes across regions - will you need to add application or data level locking or would you enforce some form of queuing?
To improve performance across regions the other approach could be to have regional caching to reduce the need to retrieve data from the master source, but this will require careful management of time to live values for cached data so that it remains within an acceptable freshness threshold which will differ between data types.
## Auth dependencies are the hidden failure mode
If your identity provider or authorization service is centralised then a regional API failure may be the least of your worries if auth itself is unavailable. API Connect SaaS uses IBMID for it's management plane identity provider, highly available in it's own right, but not part of our regional deployment. Importantly though it's not involved in runtime authentication for customer APIs or their developer portals so any failure doesn't cascade to impact live traffic.
If you can validate JWTs locally without needing to call out to a central service then in most cases you are good, but what happens if you need to revoke a token - do you have a robust system for sharing a revocation list?
How are you handling rate-limiting - is this maintained within the region or do you have a way to track usage across the regions? Within DataPower API Gateway the rate-limiting is maintained through the peering group, requiring a low-latency connection to keep them in-sync. For the DataPower Nano Gateway this can be externalised to your own Valkey or Redis deployment which you could deploy using cross-region replication. Whatever solution your rate limiting is based around, ensure that the period over which the rate is set aligns with the latency in your replication - for example if the replication may sometimes take more than a second you can't use per second rate limiting and would be better to calculate the equivalent over a larger period.
## Routing and traffic management
How do you route traffic through your system - starting from the consumer - do you want to expose the regions to them or should they just continue to use a known endpoint and it just works? If you are maintaining a global endpoint you will need some form of global traffic routing - either DNS-based or some form of load-balancing. If you stick with regional endpoints - how are they discovered by the consumer - are they all just servers listed in the OpenAPI specification? Do you provide guidance to the developers building against your API on how to handle retries and failover across regions?
If there are cases where there is state involved, maybe you need some form of session-stickiness to keep the traffic in the region it starts. The techniques you would use here would completely depend on the type of clients you are building for - if this is pure API clients you would need something client IP based, if it's browser based clients, cookies are an option.
If you have global endpoints what controls the routing or failover to a different region - is this purely based on health-check response, latency based or some intelligence based on the inbound IP address and which region is closest to them? For the stateless common components in our API Connect Reserved Instance console we have them available in each region and use broad GeoIP based routing to try and serve inbound traffic from their nearest endpoint with a failover - GeoIP based routing helps to a degree but IP geo-location isn't always accurate.
## Failure modes and failover
If there is an issue with one of the regions, how do you detect it and what happens next? Of course if you have to serve traffic within region it may just be a case of waiting it out.
How do you test the failover? Any failover plan is only any use if it works so it is crucial that you have a way to test this. Ideally you would identify a way simulate a failure and trigger the failover - then you can ensure your observability covers this to show what is happening during a failover. Also worth considering when you look at observability for a multi-region solution is whether you define Service Level Objectives by region or across the solution and how you track these, along with the resilience of your monitoring tooling as well.
Actual failures aren't always as cut and dried as the test however - you may find that a region is only partially impacted or continues to run just without any network connectivity. These are key factors to consider when determining the trigger for failover but also for clarifying the state of the system during the failover and what actions will be needed to move back to normal operation after the failover. It may be that you need to treat a region as completely down even when it isn't so as not to end up with split-brain across the regions data - then restore a backup there in order to return to normal afterwards. This was a fundamental part of how we used to deal with replication in Informix - where if there was a network partition we would find multiple nodes continuing to run as primary and we would need to select which node to reset. This was usually the one with a secondary server still attached, but occasionally there would be workload continuing on the standalone primary and nothing happening in the clustered one. The same principle applies here at a higher level: sometimes the safest recovery path is to treat a degraded region as completely lost and restore cleanly rather than trying to reconcile state.
Are there parts of your system that need to be disabled during a regional failure and run in a degraded mode as they add more risk or aren't as crucial to maintain availability on?
Most multi-region requirements aren't as simple as just adding another geographic location - there is a lot more to think through across the different layers of your system - data, auth, routing and how it actually will handle failures. Going back to where we started, the right answer will depend on the requirement you are building for. Latency, resilience and compliance will each take you in different directions as you design so it is key to have clarity up-front rather than trying to do everything and over-engineering a solution. For more on designing with reliability in mind from the start see [SRE Mindset in API Architecture](/blog/2026/the-sre-mindset-in-api-architecture/) or for an example of how this could be done see my post on [building a global deployment with API Connect](/blog/2025/global-deployment-with-api-connect-serving-apis-worldwide/).
---
# The SRE Mindset in API Architecture
URL: https://rickymoorhouse.uk/blog/2026/the-sre-mindset-in-api-architecture/
Date: 2026-03-07
Tags: architecture, sre

I spent a good chunk of my career working in SRE and then when the opportunity came up I took the decision to move over into an Architecture role - in some ways a change and in many ways a wider remit to continue with the types of things I'd been doing and working on in the SRE team.
## How SRE reliability principles shape architecture
Core principles from my time in SRE have definitely shaped the way I look at bringing our product to the cloud - and whilst there's still a lot of things that I (and our SRE team) wish we had done better with, I think it's a valuable insight to have when building out these systems. I think the biggest area this has influenced my way of working is a desire to be driven by real data where possible and validate my thinking with what we are seeing in reality.
## Sizing - planning for reality, not hopes
When we're building something new we often get the numbers wrong - either we're too optimistic and expect viral exponential growth or we're too pessimistic and assume no-one is interested. If however you're building something that you have experience with either directly or in a similar area there is real data available to reference.
This means you can inform your sizing estimations with a grounding in historic real world usage data. It won't always be precise and these things usually don't repeat in the same way but at least it means you are learning from something and building on the lived experience.
Even though we can capture some data to base our sizing on we still want to validate it - key to any architecture is testing the decisions you've made - both in small parts and end to end. For load testing I would want to use realistic numbers that can be proportioned against the expectations - so validating each point in the scale up - over a short term to understand the characteristics - then do some additional longer running load tests to ensure things continue to operate over time as you would expect. This also needs to be combined with your observability plan - if you get these in place early you can use them as part of your load testing validation and capture valuable insights into your system.
This then leads into the next set of sizing decisions - how and when do you scale? For each part of your system you need to look at how scaling would apply and the impact this has on the neighbouring components - e.g. if we just scale up the API Gateway to handle more load but haven't ensured we have the right rate limiting or considered the capacity of the backend microservices serving the API we could just be opening ourselves up for too much traffic and different types of failure. At each layer we need to consider how much capacity we need, how long the different scaling strategies would take and the cost implications of allowing this to scale automatically. Some parts of the system may be so critical or growth is directly proportional to your revenue so that an increase in cost with autoscaling may be the desired outcome.
## Observability - you can't fix what you can't see
Can you tell what is going on in the system? As systems become more complex and more microservices are added it is fundamental to be able to answer these types of questions about specific areas. Building systems for observability from the start makes it a lot easier than bolting this on afterwards. Defining standard approaches and formats for observability means that you're not deciding for each component independently but you have something that everything in the system can adopt. These need to cover the three main pillars of observability - Metrics, Logs and Traces.
- **Metrics** give you a lightweight numeric representation of parts of your system that you can graph over time - they are useful for indicators as to how loaded things are or how slow certain flows are performing. For example, response times, payload sizes and error count
- **Traces** let you follow the end to end journey of a request through your system detailing the steps it has taken along the way and connections between microservices and processes. This would show the inbound request from when it hits your API Gateway on to each microservice that is involved in responding to that request - giving you full details of what and when at each stage. In fact your traces are really the living illustration of your architecture.
- **Logs** give you insight into the path through your code that is being taken or the error cases you are hitting. Having consistently formatted structured logs with request ids to correlate what request the log relates to or tie it to the trace without guessing.
I read a comment somewhere that diagnosing problems in a microservices architecture is like a murder mystery - however much you like solving these, you don't want to have to at 3am at the end of a pager, so in logging we need to think about this up front.
Metrics will give you an easy snapshot of if there is a problem, Traces will show you which service is causing the problem and the logs will tell you why. These will also have a significant impact on the costing of your solution - metrics being the cheapest and logs being the most expensive as they will scale up rapidly as your volumes increase - 1 transaction could result in 10-100 log lines depending on the complexity and how verbose your logging is. This is also why it is key to be able to dynamically adjust log levels - you can keep the general volume down and increase it as necessary.
As with sizing we mustn't get carried away with the trillions of transactions we're hoping to see on day 1 with 100% uptime - we need to set some expectations (Service Level Objectives) as to what real use of the system needs to look like and what our customers would accept. This is not what the SLA is or what the ideal requirement is (that would be super fast and always available) but the acceptable level of availability and responsiveness day to day. In some scenarios waiting for 5 seconds for data is fine, and others it is needed within milliseconds and each delay costs money. Just like some scenarios can cope with a retry and others can't.
Sizing the system, ensuring we can answer the crucial questions about what is happening in it and appropriately meet our users' expectations are some of the ways my SRE experience has directly fed into my architecture work. Equally important is designing for resilience - ensuring the system can fracefully handle failure rather than just hoping it won't happen. That's one of the next topics I plan to explore here, looking at failure modes and resilience patterns building from what I've covered here.
---
# Building an AI Agent: From Inspiration to Implementation
URL: https://rickymoorhouse.uk/blog/2026/building-an-ai-agent-from-inspiration-to-implementation/
Date: 2026-02-16
Tags: ai, coding, golang, agent, architecture
I've been fascinated by the idea of AI agents for a while now - programs that can not just chat, but actually _do_ things. A few weeks back I came across Clawdbot - now called [OpenClaw](https://openclaw.ai) and it clicked something in my brain. This had a great potential for proactive workflows with a regular trigger to identify things that needed doing and the ability to extend itself with additional code and updates to it's own configuration. Very powerful, but also very risky if not controlled. I set this up intially as it's own user account and then fairly soon moved it into an isolated VM.
I really liked the potential here but wasn't comfortable with the complexity of the code and the power I was giving it or would need to give it to do more interesting tasks - I've still not let it access calendar or e-mail for example. However if I could build something I could read all the code for and understand - with my own selection of controls and tools that are limited according to my own sense of risk level.
So rather than just using someone elses platform I embarked on building something smaller and more personal that I could tune to the things I wanted it to do. This became a great learning experience in understanding the basics at the core of what is needed in an Agent but also how this can get much more complex as you start to deal with things like memory and control.
## Why Go?
Python would have been the obvious choice. It's the default language of AI, with libraries for everything, but I wanted to start with API calls rather than libraries and Go offered something different:
- **Single binary deployment** - no virtual environments, no dependency hell
- **Straightforward concurrency** - agents need to do multiple things at once
- **Static typing** - catching mistakes at compile time matters when your agent is taking real actions
## The Architecture
The agent follows a pattern you'll recognise if you've looked at OpenClaw or similar frameworks:
1. **Model** - The brain. Currently I'm switching between Ollama, MiniMax and Claude all using their Anthropic compatible API
2. **Planner** - Takes the user's request and figures out what steps are needed
3. **Executor** - Runs the planned steps, handling tool calls and results
4. **Tools** - The verbs the agent can use (files, commands, web search, etc.)
```
User Request → Planner → [Tool Calls] → Executor → Results
↑ │
└────── Feedback ←────────┘
```
The key insight from OpenClaw that shaped this was **deliberate action**. The agent doesn't just guess what to do - it reasons about the next step, executes it, observes the result, and decides what to do next. That loop is the heart of it.
## The Tool Selection
So far I've created a set of basic tools:
| Tool | Purpose |
|------|---------|
| `read_file` / `edit_file` | Working with code and notes |
| `exec_cmd` | Running shell commands |
| `list_files` | Exploring directory structures |
| `web_search` / `web_fetch` | Research without leaving the terminal |
| `todoist` | Task list for the agent to work on without always being directly prompted |
The interesting part wasn't adding tools - it was **deciding what not to add**. Every tool is a potential attack surface or a source of confusion. The discipline of a small, thoughtful toolbox is more valuable than a big one.
## Lessons from Building It
### Context is everything
The agent is only as good as what it knows about the world it's operating in. Early versions missed crucial details because I didn't pass the right context to the model. Now I spend more time thinking about what context to provide than about the tool infrastructure itself.
### Tool design matters enormously
Badly designed tools create bad agent behaviour. The model will find the problems with the tools and either hit them multiple times causing more to clean up or work around them in interesting new ways. A tool that returns too much information overwhelms the context. Too little, and the agent is flying blind. The best tools do one thing well and return structured, predictable output. One of the things I found that helped here was when the agent was struggling with the tools - either through bugs or a lack of clarity I had it look at improving them in context so the specific error fed into the solution. An example of this was it kept trying to use the exec tool to write new files and hitting issues as my protections were blocking multi-line pipes, where as I'd intended this to be done through the edit tool - so asked the agent to improve the description and metadata for the edit tool to make it clear it could be used for this.
### Trust but verify
The agent can take actions - that's the point. But it needs guardrails. I've built in permissions and observability so I can see what it's trying to do before it does something irreversible. The goal is helpful, not dangerous.
## What's Next
Right now the agent is genuinely useful for my workflow. It writes drafts, fetches information, organises files, and saves me clicks. But there's more to do:
- **Memory** - I'm storing memory in markdown but want to explore doing something better here for easier retrieval
- **Multi-step tool composition** - chaining tools intelligently - often today it feels like there are more steps used than really necessary so seeing potential for optimisation
- **Better planning** - fewer back-and-forth iterations
The thing I'm most proud of isn't any single feature. It's that it exists, that I built something that actually works, and that it reflects how I think about AI: not as magic, but as a tool.
I'll probably share more findings as I experiment more - for now this is working for me as a collaborator on code development (including it's own code base) and a research assistant.
_The code lives in a private repo for now as this is intended as a personal agent not a framework, but the concepts here are universal. If you're thinking about building an agent, start small, choose your tools carefully, and remember: the goal is to build something that helps you._
## References I found helpful
- [How to build an agent](https://ampcode.com/notes/how-to-build-an-agent) from Amp Code - I used this one as a starter to see the basic principles.
- [Anthropic API guide](https://platform.claude.com/docs/en/api/messages/create) and [Ollama anthropic compatibility](https://docs.ollama.com/api/anthropic-compatibility) helped me go beyond the SDK use from the first example
- [Telegram Bot Go Framework](https://github.com/go-telegram/bot) let me go beyond CLI based chat to talk to my agent from anywhere
---
# My Blog
URL: https://rickymoorhouse.uk/projects/blog/
Date: 2026-02-02
Tags: blog
My site is powered by Hugo and lives on GitHub. I use GitHub Actions to build and deploy the site to BunnyCDN.
# Hugo
After previously using a self-built blogging engine and then Wordpress for a while, I decided that I didn't want to deal with running a database backed dynamic site any longer and that a static file based site would both perform better and be simpler to keep running. I looked at a number of different static site generators and played with [Jekyll](https://jekyllrb.com) and [Pelican](http://getpelican.com) but in the end decided on [Hugo](https://gohugo.io). This was primarily as I have been moving more to building things in Go and the templating system and site structure felt like a good fit for my needs.
The search on the site is powered by [pagefind]() - which still could do with some fine tuning and aligning the styles but it mostly works nicely for now.
## Bunny CDN
I've been through a number of places the static site lived - from several VPS providers to an S3 bucket fronted by Cloudfront, then when I was reading about some European hosting options I came across [Bunny](https://bunny.net) and decided to try their CDN as an option. It seemed to perform well - easy to update and good response times.
I have a storage zone in London with a replica in Brazil and a Pull Zone configured with Europe and North America zones configured. I don't remember why I chose Brazil for the storage replica! I generally see a good level of cache hits in the stats they provide.

## Github Actions CI/CD
The site is automatically deployed when I push to the main branch in it's [github repo](https://github.com/rickymoorhouse/blog) which makes it easier to tweak or add to without needing to be at a computer.
I have a couple of shortcuts configured on my phone so I can easily post [Photos](/photos) and [Locations](/travel) whilst I'm away from home which use [Working Copy](https://workingcopy.app) to push to github. Occasionally I will also use working copy or the GitHub mobile app to edit more but usually it's from the shortcuts.
## Travel map
Updated a bit from the original [Places visited map](/blog/2018/places-visited-map/) which worked from front-matter, I've since moved to a separate data folder of locations to show on the map as yaml files containing the location, name, some additional metadata and an optionally a link and photo to include. This looks something like:
```yaml
title: "San Jose"
layout: travel
datePosted: 2022
photo: /travel/photos/sanjose.jpg
lat: 9.9332828
lng: -84.0776586
description: >
# Hotel Presidente, San Jose
Year: 2022
```
I'm not using all of this yet but wanted to include some additional elements for the future. This is then processed into GeoJSON in a [layout template](https://github.com/rickymoorhouse/blog/blob/main/layouts/geojson.json?short_path=b97ff09). The map itself is still powered by [Mapbox GL](https://docs.mapbox.com/mapbox-gl-js/guides/) using the [map display template](https://github.com/rickymoorhouse/blog/blob/main/layouts/map.html).
## Recent Changes
- Added `tagged-posts` shortcode to list blog entries with a given tag using `short-list-item` partial
- Added theme switching support to MapBox maps
- Built flights.json generation system with Python script, integrated into GitHub Actions
- Added projects section with styling improvements
- Added microblog section with a bot to post from Telegram
---
# Global Deployment with API Connect - Serving APIs Worldwide
URL: https://rickymoorhouse.uk/blog/2025/global-deployment-with-api-connect-serving-apis-worldwide/
Date: 2025-09-17
Tags: apiconnect, global
## Why Global API Deployment Matters
If you have customers around the world, serving your APIs from a global footprint significantly improves their experience by reducing latency and increasing reliability. With API Connect's multi-region capabilities, you can ensure users call your APIs from locations closest to them, providing faster response times and better resilience against regional outages.
In this guide, I'll walk through deploying APIs to the 6 current regions of the API Connect Multi-tenant SaaS service on AWS. At the time of writing, these regions are:
- North America: N. Virginia
- Europe: Frankfurt, London
- Asia-Pacific: Sydney, Mumbai, Jakarta
I'll use N. Virginia as the initial source location and demonstrate how to synchronize configuration across all regions.

## Automatically Deploy APIs and Products to all locations
To maintain consistency across regions, you'll need a reliable deployment pipeline. This pipeline should handle the deployment of APIs and products to all regions whenever changes are made to your source code repository.
You can build this pipeline using either:
- The [sample GitHub Action workflow](https://github.com/ibm-apiconnect/actions) provided by IBM
- Custom scripts based on the [example CLI scripts](https://github.com/ibm-apiconnect/devops) in the devops repository
This automation ensures that whenever you merge changes to your main branch, your APIs and products are consistently deployed across all regions without manual intervention.

## Create an API Connect instance in each region
Before configuring your global deployment, you'll need to:
1. Create an API Connect instance in each target region
2. Use the same configuration as your source location (N. Virginia in this example)
3. Specify a unique hostname for each regional instance
**Pro Tip:** Each paid subscription for API Connect SaaS includes up to 3 instances which can be distributed across the available regions as needed. For a truly global footprint covering all 6 regions, you'll need two subscriptions.
## Configure the portal for the source location
For developer engagement, you'll need a portal where API consumers can discover and subscribe to your APIs. In my implementation, I chose the new [Consumer Catalog](https://consumer-catalog.us-east-a.apiconnect.automation.ibm.com/ibm/production) for its simplicity and ease of setup.
While I didn't need custom branding for this example, I did enable approval workflows for sign-ups. This allows me to:
- Review all registration requests
- Control access to sensitive APIs
- Manage who can subscribe to which products

## Configure ConfigSync to push configuration changes to all regions
The key to maintaining consistency across regions is ConfigSync, which pushes configuration changes from your source region to all target regions. Since ConfigSync operates on a source-to-target basis, you'll need to run it for each target region individually.
My implementation uses a bash script that:
1. Sets the source region (N. Virginia)
2. Defines common properties for all target regions
3. Loops through each target region, setting region-specific properties
4. Runs the ConfigSync tool for each region

Here's the script I use:
```bash
#!/bin/bash
# US East is always the source catalog
export SOURCE_ORG=ibm
export SOURCE_CATALOG=production
export SOURCE_REALM=provider/default-idp-2
export SOURCE_TOOLKIT_CREDENTIALS_CLIENTID=599b7aef-8841-4ee2-88a0-84d49c4d6ff2
export SOURCE_TOOLKIT_CREDENTIALS_CLIENTSECRET=0ea28423-e73b-47d4-b40e-ddb45c48bb0c
# Set the management server URL and retrieve the API key for the source region
export SOURCE_MGMT_SERVER=https://platform-api.us-east-a.apiconnect.automation.ibm.com/api
export SOURCE_ADMIN_APIKEY=$(grep 'us-east-a\:' ~/.apikeys.cfg | awk '{print $2}')
# Set common properties for all targets - in SaaS the toolkit credentials are common across regions.
export TARGET_ORG=ibm
export TARGET_CATALOG=production
export TARGET_REALM=provider/default-idp-2
export TARGET_TOOLKIT_CREDENTIALS_CLIENTID=599b7aef-8841-4ee2-88a0-84d49c4d6ff2
export TARGET_TOOLKIT_CREDENTIALS_CLIENTSECRET=0ea28423-e73b-47d4-b40e-ddb45c48bb0c
# Loop through the other regions to use as sync targets
# Format: eu-west-a (London), eu-central-a (Frankfurt), ap-south-a (Mumbai),
# ap-southeast-a (Sydney), ap-southeast-b (Jakarta)
stacklist="eu-west-a eu-central-a ap-south-a ap-southeast-a ap-southeast-b"
for stack in $stacklist
do
# Set the target management server URL for the current region
export TARGET_MGMT_SERVER=https://platform-api.$stack.apiconnect.automation.ibm.com/api
# Retrieve the API key for the current region from the config file
export TARGET_ADMIN_APIKEY=$(grep "$stack\:" ~/.apikeys.cfg | awk '{print $2}')
# Run the ConfigSync tool to synchronize configuration from source to target
./apic-configsync
done
```
For managing API keys, I store them in a configuration file at `~/.apikeys.cfg` where each line contains a region-key pair in the format `region: apikey`. This approach keeps sensitive credentials out of the script itself - for a more production ready version this api key handling would be handed off to a secret manager.
## Verify that everything works as expected
After setting up your global deployment, it's crucial to verify that everything works correctly across all regions. Follow these steps:
1. **Test the source region first:**
- Register a consumer organization in the portal
- Subscribe to a product containing an API you want to test
- Use the "Try now" feature to invoke the API and verify it works
2. **Verify ConfigSync completion:**
- Check logs to ensure the ConfigSync job has completed successfully for each region
- Verify that all configuration changes have been properly synchronized
3. **Test each target region:**
- Call the same API from each region using the appropriate regional endpoint
- Verify that response times, behavior, and results are consistent
- Check analytics to confirm that traffic is being properly recorded in each region
4. **Monitor for any issues:**
- Watch for any synchronization failures or configuration discrepancies
- Address any region-specific issues that might arise
## Possible next steps
Once your global API deployment is working, consider these enhancements:
- **Implement global load balancing** to automatically route customers to the closest region based on their location
- **Set up cross-region monitoring** to track performance and availability across all regions
- **Implement disaster recovery procedures** to handle regional outages gracefully
## Conclusion
A global API deployment strategy with API Connect provides significant benefits for organizations with worldwide customers. By following the approach outlined in this guide, you can:
- Reduce latency for API consumers regardless of their location
- Improve reliability through geographic redundancy
- Maintain consistent configuration across all regions
- Simplify management through automation
While setting up a global footprint requires some initial configuration, the long-term benefits for your API consumers make it well worth the effort.
---
# API Connect Quick Check
URL: https://rickymoorhouse.uk/blog/2025/api-connect-quick-check/
Date: 2025-07-05
Tags: apiconnect
This script originated as part of a much wider framework of tests that we put together when I was in the API Connect SRE team. However I’ve found this set of functions to be something useful to be able to validate quickly from time to time in different contexts to give a high level answer to ‘Is it working?’
The steps this script takes are as follows:
- Authenticate to the API Manager Platform API and retrieve an access token
- Take a templated API and Product and modify it to return a unique value
- Publish this API to a nominated catalog
- Invoke the API through the gateway (looping until a successful response is seen)
- Query the Analytics APIs to find the event logged for this invocation (again looping until found)
Whilst the entire test frameworks a lot of assumptions around how our environments are built and deployed, this test was relatively standalone - and I just needed to make a couple of updates to it to work outside of our cloud deployments - add support to turn off certificate validation and for username/password instead of API Key based authentication. Take a look at the script on GitHub.
If you want to try this in your own environment you can follow these steps:
1. Clone the repository
```bash
git clone https://github.com/ibm-apiconnect/quick-check.git
```
3. Install the python required dependencies
```bash
pip install -r requirements.txt
```
3. Identify the appropriate credentials to use for your stack - either username/password or an api-key if you are using an OIDC registry and set these as environment variables (APIC_API_KEY or APIC_REALM, APIC_USERNAME & APIC_PASSWORD) or use the command line parameters - either of:
- `-u -p -r provider/default-idp-2` (Local user registry or LDAP)
- `-a ` (OIDC e.g. SaaS)
4. Download the credentials.json file from the toolkit download page to identify the client id and client secret for your environment - these can either be set as environment variables (CLIENT_ID / CLIENT_SECRET) or as command line parameters (--client_id / --client_secret)
5. Run the script according to the usage examples
```bash
python api-deploy-check.py -s -o -c [credential parameters]
```
If successful, you should see output like this:

I'd be interested to hear if you find this useful or if you have other similar utilities you use already - let me know!
Originally posted on the [IBM API Connect Community Blog](https://community.ibm.com/community/user/blogs/ricky-moorhouse1/2025/03/28/api-connect-quick-check-script)
---
# Status Light
URL: https://rickymoorhouse.uk/projects/status-light/
Date: 2025-05-11
Tags: raspberrypi, coding
Updated
Whilst working from home it's useful for the family to know when I am on a video call or just a voice call. I was first looking at [Busy bar](https://busy.bar/preview) which I came across via [Hiro Report](https://hiro.report), but couldn't justify the cost of it and as I had a raspberry pi zero and a [Blink!](https://shop.pimoroni.com/products/blinkt?variant=22408658695) sitting around, I decided to build something simple myself. Maybe one day I could make it more complex and build a version using the [Pico 2 W Unicorn Galactic](https://shop.pimoroni.com/products/space-unicorns?variant=40842033561683)?

## Hardware
- [Raspberry Pi Zero W](https://shop.pimoroni.com/products/raspberry-pi-zero-w?variant=39458414264403)
- Power Supply
- [Blink!](https://shop.pimoroni.com/products/blinkt?variant=22408658695)
## Software Part 1 - LED Control Server
This is the application that runs on the Raspberry Pi and controls the lights based on a simple API call. I deploy this to my Raspberry Pi through [Balena](https://www.balena.io/) for ease of management and updates - then I can just push a new copy of the code into git and balena will automatically deploy it to my Raspberry Pi.
The API Call is very simple and currently accepts a GET request with parameters for the red, green and blue values (between 0 and 255) - really this should probably be a PUT request but using GET made testing with a browser simpler. The light is switched off with a DELETE call (or another GET with 0 for each parameter).
You can see the code for this in the `light` directory.
## Software Part 2 - Webcam detection tool
This part runs on my laptop and detects when the webcam is in use through monitoring the system log - if a change in state is detected, it then sends an API call to the Raspberry Pi to switch the light on or off as appropriate.
The tricky part here was the detection of the webcam - I found a few different samples and a useful reddit thread (which I can't find now - will add the link later!) on ways to detect the webcam being operational on MacOS and it seems it is liable to change between MacOS versions - looking for eventMessages containing `AVCaptureSessionDidStartRunningNotification`, `AVCaptureSessionDidStopRunningNotification` or `stopRunning` seems to work for the things I've tested on Sequoia.
The alternative route I was considering was to use [OverSight](https://github.com/objective-see/OverSight) to trigger a CLI app and leave the detection to them - but having the CLI detect it was more interesting to build.
You can see the code for this part in the `cli` directory.
The code for this project lives at [github.com/rickymoorhouse/status-light](https://github.com/rickymoorhouse/status-light/).
---
# Status Light
URL: https://rickymoorhouse.uk/blog/2025/status-light/
Date: 2025-05-11
Tags: raspberrypi, coding
Whilst working from home it's useful for the family to know when I am on a video call or just a voice call. I was first looking at [Busy bar](https://busy.bar/preview) which I came across via [Hiro Report](https://hiro.report), but couldn't justify the cost of it and as I had a raspberry pi zero and a [Blink!](https://shop.pimoroni.com/products/blinkt?variant=22408658695) sitting around, I decided to build something simple myself. Maybe one day I could make it more complex and build a version using the [Pico 2 W Unicorn Galactic](https://shop.pimoroni.com/products/space-unicorns?variant=40842033561683)?

## Hardware
- [Raspberry Pi Zero W](https://shop.pimoroni.com/products/raspberry-pi-zero-w?variant=39458414264403)
- Power Supply
- [Blink!](https://shop.pimoroni.com/products/blinkt?variant=22408658695)
## Software Part 1 - LED Control Server
This is the application that runs on the Raspberry Pi and controls the lights based on a simple API call. I deploy this to my Raspberry Pi through [Balena](https://www.balena.io/) for ease of management and updates - then I can just push a new copy of the code into git and balena will automatically deploy it to my Raspberry Pi.
The API Call is very simple and currently accepts a GET request with parameters for the red, green and blue values (between 0 and 255) - really this should probably be a PUT request but using GET made testing with a browser simpler. The light is switched off with a DELETE call (or another GET with 0 for each parameter).
You can see the code for this in the `light` directory.
## Software Part 2 - Webcam detection tool
This part runs on my laptop and detects when the webcam is in use through monitoring the system log - if a change in state is detected, it then sends an API call to the Raspberry Pi to switch the light on or off as appropriate.
The tricky part here was the detection of the webcam - I found a few different samples and a useful reddit thread (which I can't find now - will add the link later!) on ways to detect the webcam being operational on MacOS and it seems it is liable to change between MacOS versions - looking for eventMessages containing `AVCaptureSessionDidStartRunningNotification`, `AVCaptureSessionDidStopRunningNotification` or `stopRunning` seems to work for the things I've tested on Sequoia.
The alternative route I was considering was to use [OverSight](https://github.com/objective-see/OverSight) to trigger a CLI app and leave the detection to them - but having the CLI detect it was more interesting to build.
You can see the code for this part in the `cli` directory.
The code for this project lives at [github.com/rickymoorhouse/status-light](https://github.com/rickymoorhouse/status-light/).
---
# Remote Gateway on Openshift
URL: https://rickymoorhouse.uk/blog/2025/remote-gateway-on-openshift/
Date: 2025-02-07
Tags: apiconnect, gateway
This post should guide you through the steps on how to deploy a datapower gateway to use as a remote gateway with API Connect Reserved instance, optionally configuring the inbound management traffic through IBM Cloud Satellite Connector.

## Installing the Operators
To install the operators in your cluster, the steps are as described in the documentation on how to [install the operators](https://www.ibm.com/docs/en/api-connect/10.0.8?topic=openshift-installing-operators)
## Set up certificates
Again follow the [steps for creating certificates](https://www.ibm.com/docs/en/api-connect/10.0.8?topic=openshift-setting-up-certificate-issuer) in the documentation.
## Deploy the Gateway Cluster
Deploying the gateway cluster into Openshift is just a case of creating the GatewayCluster CR - you can start from [this template](gateway.template.yaml). NB. You will need to ensure that `spec.license.use` is set to `production` if you are using the RI provided image registry as we don't provide the nonproduction images.
- Create a pull-secret with access to download the datapower images and reference it under imagePullSecrets. You can download the image to mirror to your registry from the 'Download Gateway' button in the reserved instance Config Manager.
- Create a secret containing the password for the datapower admin user and ensure it is referenced under `adminUser` - you can use the following command to create this:
oc create secret generic admin-secret --from-literal=password={SET-PASSWORD-HERE!}
- Update `imageRegistry` to point to your image registry.
- Update the `jwksUrl` for your reserved instance, this needs to be the platform api endpoint for the reserved instance followed by `/api/cloud/oauth2/certs` - you can find the platform api endpoint url from the 'Download Clients' link in the API Manager interface.
- Select and configure the [appropriate profile](https://www.ibm.com/docs/en/api-connect/10.0.8?topic=licensing-datapower-gateway-deployment-profile-limits) for your cluster.
- Create a secret with the CA the reserved instance endpoints are signed by - Let's Encrypt X2 Root CA ([Download from the Let's Encrypt site](https://letsencrypt.org/certs/isrg-root-x2.pem)) and ensure the `secretName` for `mgmtPlatformEndpointCASecret` points to this.
curl https://letsencrypt.org/certs/isrg-root-x2.pem -o isrg-root-x2.pem
oc create secret generic isrg-root-x2 --from-file=ca.crt=isrg-root-x2.pem
- [Optional] If you are routing the inbound traffic through IBM Cloud Satellite Connector, you will need to configure the hostname for the `gatewayManagerEndpoint` to match the private cloud endpoint hostname for your connector - typically `c-01.private.{region}.link.satellite.cloud.ibm.com`.
- Apply the gateway cluster yaml
- You can check the status of the cluster using `oc get gatewaycluster`. If you see any issues you can use `oc describe gatewaycluster` for more details.
## Set up Satellite Connector [optional]
Optionally, deploy a satellite connector agent on the same cluster as the remote gateway
- [Create a Satellite Connector](https://cloud.ibm.com/docs/satellite?topic=satellite-create-connector&interface=ui)
- [Deploy the agent](https://cloud.ibm.com/docs/satellite?topic=satellite-run-agent-locally&interface=ui)
- Create a Connector Endpoint for the gateway management interface [docs](https://cloud.ibm.com/docs/satellite?topic=satellite-connector-create-endpoints&interface=ui). For the Gateway management endpoint you will need the following details:
- Destination FQDN: `{gateway-cluster-name}-datapower.{namespace}.svc` e.g. `api-gateway-datapower.apicri-gateway.svc`
- Destination Port: 3000
- TCP
## Register gateway with Reserved Instance
Create TLS Client Profile so that the manager can trust the CA that signs the certificate for the gateway management endpoint. This can be done through the RI Config manager under TLS.
- Create a Trust Store containing the CA Certificate which can be obtained by copying out the ca.crt from the `gateway-manager-endpoint-secret` and putting it in a file named ca.pem (API Connect needs the .pem extension for the upload to be accepted.)
- Create TLS Client Profile referencing the Trust store created
Create TLS Server profiles to present to clients invoking the APIs:
- Create TLS Key Store containing the certificate and private key to present - typically these would be obtained through an external Certificate Authority.
- Create a Server profile referencing the key store created.
To register the gateway on the 'Gateways' tab you will need the following details:
- URL of management endpoint: If using Satellite, this is the link endpoint URL including the port number. If not, this will be the hostname from the gatewayManagerEndpoint in the gateway cluster CR.
- TLS Client Profile: profile created above
- Base URL of API Invocation endpoint: The host from the gatewayEndpoint in the CR that inbound clients will use
- TLS Server Profile: profile created above
---
# Lambda Integration in IBM API Connect on AWS
URL: https://rickymoorhouse.uk/blog/2023/lambda/
Date: 2023-03-23
Tags: apiconnect, serverless, aws
This blog post will provide you an overview of our Lambda integration in API Connect on AWS, what you could use it for and a simple worked example of setting this up. If you’d prefer you can [watch me demonstrate this in our video on YouTube](https://youtu.be/NDKfzBSCvVA).
Lambda is serverless computing platform provided by Amazon Web Services (AWS) which lets you build and deploy your code in a number of different programming languages with easy integrations to AWS services without having to manage infrastructure or servers. This makes it an ideal place to build out your API implementation and when you combine this with our API Connect on AWS SaaS offering you can quickly build, manage and socialise your APIs without worrying about the infrastructure behind them.
Using our Lambda policy in the SaaS service makes this simple and straight forward to integrate these so you can build out your apis around numerous different AWS services then manage them centrally through API Connect, sharing them with consumers through our customisable developer portal.
In order to manage the integration securely we use AWS Security Token Service (STS) so there is no need for you to give API Connect the credentials for your AWS account, you can just create an IAM role and grant permission for API Connect to assume that role.
The API Connect service is running in our AWS account and we have a fixed STS role that the service uses for each region:
| Region | Role |
|--------|------|
| US East | arn:aws:iam::623947394061:role/ibm-apiconnect-us-east-a |
| Frankfurt | arn:aws:iam::623947394061:role/ibm-apiconnect-eu-central-a |
| London | arn:aws:iam::623947394061:role/ibm-apiconnect-eu-west-a |
In your AWS account you would set up a role that has permission to invoke your Lambda function(s) and set up the principal for the trust policy to be our service role and the external ID to be your provider org ID of your API Connect service instance. You can set this role to grant permission for just a single lambda function or multiple depending on what you need.
Within API Connect you will find the Lambda policy in the API Assembly editor on the Gateway tab along with all the other policies you can use to build out your API. The preferred model is to configure the lambda policy using the STS Assume Role option, however we do also support providing an Access Key ID and Secret Access Key. Then along with the credentials you just need to specify the name of the function and the region you have the lambda function deployed in.
To do this for yourself you can follow along with my simple worked example:
## 1. Create Lambda function
From the AWS Console, select Lambda then Create function - either start from scratch or make use of the ‘Hello World’ blueprint example. If you start from scratch and want to use the simple echo function I [demonstrate in the video](https://youtu.be/NDKfzBSCvVA), give your function a name and select NodeJS as the Runtime - you can leave all the other settings the same unless your organisation has specific requirements around roles and permissions. Then click Create function.
Here is the code for the simple example from the video, which you can copy and paste into your function - alternatively you can use an existing function or write something more useful yourself:
```js
export const handler = async(event) => {
// TODO implement something more interesting here!
const response = event;
return response;
};
```
After the code is updated in the function, click Deploy.
Take a note of the function name and region your function is deployed in - both are part of the displayed function ARN - `arn:aws:lambda:{{region}}:{{account}}:function:{{functionName}}`
## 2. Create a role
Now you have the function created you will need to create a role to grant API Connect permission to assume which can invoke the function - for this, go to IAM and select [Roles](https://us-east-1.console.aws.amazon.com/iamv2/home?region=us-east-1#/roles) within the AWS Console.
- Select Create role
- Select Custom trust policy
- Update the trust policy to have set the Principal to the API Connect role for the region you are using (see the table above) and set the “Condition” to require an external ID of the provider org you are using in the API Connect service- you should have something like the following:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::623947394061:role/ibm-apiconnect-eu-central-a"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "ac51909e-a379-4153-a0e8-ef4a25a83405"
}
}
}
]
}
```
Next, create a permission policy for the role to allow it to invoke lambda functions - something like this (you can also specify the function within the Resource field to limit which lambda functions API Connect can invoke):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
Now you have the Lambda function and Role configured we’re ready to start making use of this function within API Connect
## 3. Create your API in API Connect
To do this, open API Manager - if you don't already have a trial instance to use, you can [create a free trial now]().
- Select *Develop APIs and Products*.
- Create a new API using the Add button and selecting *API (from REST, GraphQL or SOAP)*.
- Select *New OpenAPI*.
- Complete the details for the name and path and click *Next*.
- Confirm the security options and click *Next*.
Now you have completed the guide to create the basic API you can set up the OpenAPI specification for it as you would like before moving on to configure the implementation. To configure the implementation, select the Gateway tab, remove the default Invoke policy by hovering over it until you see the bin icon - and then click it.
You can now drag the Lambda policy across in its place and fill in the details from your Lambda policy as the parameters (role, function name and region).
Now you have the Lambda policy in place you can Save the API, and toggle the Online indicator to make the API available to test and then try it out under the *Test* tab.
There we have an API implemented end to end from a serverless function in AWS Lambda through to defining the OpenAPI spec for it and managing it in API Connect. You could now go on to share this API with Consumers through the Developer Portal, or continue to build out the functionality with additional policies first.
Try it for yourself by signing up for our [free 30 day trial](https://register.automation.ibm.com/apic/trial/aws?source=blog_2023-03-23) today.
---
# Extending our sample API with conditionals and mocking
URL: https://rickymoorhouse.uk/blog/2023/extending-our-sample-api-with-conditionals-and-mocking/
Date: 2023-03-08
Video demo showing how you can use conditional logic and mocking in API Connect on AWS using our sample order tracking API as an example.
---
# Invoke IBM Cloud Functions from API Connect
URL: https://rickymoorhouse.uk/blog/2022/ibm-cloud-functions/
Date: 2022-10-25
Tags: apiconnect, serverless
[Cloud functions](https://cloud.ibm.com/functions/learn/concepts) offer an easy way to build functionality and only pay for the time they are actually running without having to worry about how it will be hosted - you just right the code, save it and it is ready to be invoked. The function can be invoked through an event trigger or as a REST API - in this case I'm going to show how you can trigger a function as part of your API Connect assembly flow - providing an easy way to manage and socialise the functionality you have built.
To call an IBM Cloud function you first need to exchange your IBM Cloud API Key for an IAM access key using the [IAM Authentication API](https://cloud.ibm.com/apidocs/iam-identity-token-api#authentication).
This is a case of setting up and sending a post request to IBM Cloud IAM, to do this I used a set-variable policy to configure the headers and body followed by an invoke to https://iam.cloud.ibm.com/identity/token. The set-variable looks like this:
```yaml
- set-variable:
version: 2.0.0
title: setup iam request
actions:
- set: message.headers.content-type
value: application/x-www-form-urlencoded
type: string
- set: message.headers.accept
value: application/json
type: string
- set: message.body
type: string
value: >-
grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$(iam-apikey)
```
Once you have this access key you can use this to call your function using the endpoint provided in the UI:
{
For the authentication to the function URL we need to set the Authorization header to `Bearer {access_key}` where access_key is from the body of the previous request, so to obtain this we can use a Parse policy to parse the returned json, and then another set-variable policy to configure the headers for the Function invoke. This time the set-variable looks like this:
```yaml
- set-variable:
version: 2.0.0
title: setup function call
actions:
- set: message.headers.authorization
value: Bearer $(iam.body.access_token)
type: string
- set: message.body
value: $(request.body)
type: any
- set: message.headers.accept
value: application/json
type: string
```
As you can see we're setting the authorization and accept headers, and passing the original request body from the inbound request. We follow this with an invoke of the function URL and a map, because the JSON returned from the function API includes details on invocation as well as the defined response:
{
The end to end flow looks like this:
{
Here is the [complete sample swagger file](https://gist.github.com/rickymoorhouse/95ca5237bf93f31c2d1629b94662882d) which can be used in any API Connect deployment, including our new [API Connect service on AWS](https://register.automation.ibm.com/apic/trial/aws?source=blog_2022-10-25)
---
# Webinar: Launch of new API Connect service on AWS
URL: https://rickymoorhouse.uk/blog/2022/webinar-launch-of-new-api-connect-service-on-aws/
Date: 2022-06-29
---
# Debugging jobs in kubernetes
URL: https://rickymoorhouse.uk/blog/2021/debugging-jobs-in-k8s/
Date: 2021-07-20
Tags: kubernetes
As jobs are often short running and finish before you can check anything within the pod, often it's helpful to make the pod run for longer to be able to inspect the environment and re-run the job manually.
One way to do this is to extract the yaml definition for a previous run of the job and create a pod definition replacing the command with an endless sleep.
kubectl get pod {previous-job-pod} -o yaml > pod.yaml
Then edit the pod.yaml, removing the `status` block and the additional metadata referring to the previous job so the metadata only contains name and namespace
The comand then needs to be updated/specified with something like this:
command:
- /bin/sh
- '-c'
- while true; do echo hello; sleep 10000; done
Then use `kubectl apply -f pod.yaml` to deploy the new pod definition to your cluster and you will have a long running pod with the environment and code for the job.
---
# Custom e-mail notifications for your provider organisation
URL: https://rickymoorhouse.uk/blog/2021/custom-e-mail-notifications-for-your-provider-organisation/
Date: 2021-07-05
---
# Avoid delays from validate compilation in your APIs
URL: https://rickymoorhouse.uk/blog/2021/avoid-delays-from-validate-compilation-in-your-apis/
Date: 2021-07-01
When re-publishing an API with validation steps in it, you may well see that the first call to the API experiences higher latency than subsequent calls. This is due to the following as [described in the documentation](https://www.ibm.com/docs/en/datapower-gateways/10.0.x?topic=definitions-configuring-api-schema):
>Schemas are compiled before they are used for validation. Because the compilation process is longer than the validation process, the compiled schema artifacts are stored in a cache. The limited capacity of the cache can cause older entries to be evicted from the cache when newer entries are added. Schemas whose artifacts have been evicted from the cache must be recompiled, which can cause significant delays in validation. You can specify the capacity of the stylesheet cache in the API Gateway.
In order to avoid your API Consumers hitting this delay in their applications you can trigger this to be pre-compiled as part of your CI/CD pipeline. If you add an an additional path to your API definition that only does the validate stage of the API this allows you to trigger the compilation without running the full API. This can be then called as part of your CI/CD pipeline against each gateway in the environment after the API is published to ensure that the validation step is compiled as soon as possible to avoid your API consumers hitting the delay.
I’ve also found it useful to have this validation path return some of the context variables to assist with debugging so you can confirm the version and id of the API matches that published and you haven’t hit the previous version due to any timing issues - a pipeline could compare these ids with the one published or prior to publish, but that is out of scope for this article.
An example path implementation such as the following referencing your existing definition:
```yaml
- condition: ($operationPath() = '/validate')
execute:
- parse:
version: 2.0.0
title: parse
parse-settings-reference:
default: apic-default-parsesettings
input: message
output: ''
use-content-type: true
- validate:
version: 2.0.0
title: validate
input: message
validate-against: definition
definition: '#/definitions/simpleObject'
output: ''
description: Test validation policy
- set-variable:
version: 2.0.0
title: set-variable
actions:
- set: message.body
value: >-
{"validated":"$(session.localAddress)","api_id":"$(api.id)","api_version":"$(api.version)"}
type: string
```
If you are running gateways in kubenetes, you normally won’t be able to target the pods independently from outside of the environment. This can be worked around by creating a separate API that will be used to invoke the validate path on your API for you against the internal pod hostnames - you just need to add an invoke step for each gateway pod - using the internal hostnames of the form: {pod-name}.{service-name}.{namespace}.svc
For example in v2018:
r6d0b871026-dynamic-gateway-service-0.r6d0b871026-dynamic-gateway-service.apic.svc
Or in v10:
gateway-0.gateway-datapower-all.apic.svc
You could then use a map in this API to consolidate the responses from each gateway for assistance with any debugging.
See a full example of an [API calling across each gateways](https://gist.github.com/rickymoorhouse/ca40eedda469c0791b6804da45412c4a).
---
# Customising the API invocation hostname in v10 Reserved Instance
URL: https://rickymoorhouse.uk/blog/2021/customising-the-api-invocation-hostname-in-v10-reserved-instance/
Date: 2021-05-28
Once you have your APIs ready to be used but before sharing them with developers if is often key to have them served on your own hostname rather than the built in hostnames that come out of the box with reserved instance. For Reserved Instance v10 you can now manage the hostname used for API Calls yourself through the IBM Cloud console without needing to open a support case.
## Configure Certificate Manager Service
- If you don’t already have one, create a Certificate Manager instance
- Ensure API Connect Reserved Instance is authorised through IAM to access this certificate manager instance.
- Upload a certificate and private key for DataPower to present for your hostname to your certificate manager instance
## Configure the SNI mapping for the gateway
- Open your Reserved instance customisation interface from the top-level item from the API Connect services list with the plan of ‘Reserved’
- Select 'Gateways' and then click on the name of the gateway service you wish to configure the hostname against.
- Select your certificate manager service from the drop down
- Add the desired domain to the “Domains handled by gateway via SNI” section and select the certificate you uploaded and select Save.

## Ensure your DNS routes traffic to the gateway
The way you do this will differ, depending on your DNS provider, but you will need to create a CNAME record for the new hostname pointing to the hostname displayed under ‘Base URL of API invocation endpoint’ above the SNI mapping list.
## Update your catalog to display the new hostname
- Open the API Manager view for the provider org you wish to update and select ‘Manage Catalogs’
- Select the catalog you wish to update, ‘Catalog settings’, ‘API endpoints’ and then Edit.
- Tick the box entitled ‘Display vanity endpoint’, select ‘Catalog priority’ and then add the new hostname to the list of base endpoints and click Save:
---
# API Connect toolkit with GitHub Actions - re-usable step
URL: https://rickymoorhouse.uk/blog/2021/api-connect-toolkit-with-github-actions-re-usable-step/
Date: 2021-03-31
---
# API Connect Remote Gateway with IBM Cloud Satellite
URL: https://rickymoorhouse.uk/blog/2021/remote-gateway-via-satellite/
Date: 2021-03-09
Tags: apiconnect, satellite
API Connect Reserved instance provides the ability to add remote API gateways so that you can co-locate the gateway service with your back-end systems for improved performance. With the new announcement of [IBM Cloud Satellite](https://cloud.ibm.com/satellite/overview), you can make use of this to securely expand your API Connect footprint across cloud providers and into the on-premise datacenter close to where your applications are running.
## Create your Satellite location
To create a Satellite location you will need 3 hosts for the control plane, and at least one host to deploy DataPower on. For each of the hosts you will need to do the following:
- Set up the host prior based on the [host requirements](https://cloud.ibm.com/docs/satellite?topic=satellite-host-reqs) for Satellite.
- Register the host for RedHat updates using `subscription-manager register` - then apply a subscription to it in the [RedHat Customer Portal](https://access.redhat.com/management/subscriptions)
- Refresh the packages and enable the repositories
```bash
subscription-manager refresh
subscription-manager repos --enable rhel-server-rhscl-7-rpms
subscription-manager repos --enable rhel-7-server-optional-rpms
subscription-manager repos --enable rhel-7-server-rh-common-rpms
subscription-manager repos --enable rhel-7-server-supplementary-rpms
subscription-manager repos --enable rhel-7-server-extras-rpms
```
- Run the attach script obtained from the IBM Cloud Satellite UI to attach the host.
For the three hosts to form the control plane, you will need to assign them to the Satellite control plane through the UI or CLI.
## Install DataPower in the Satellite location
- [Download](https://www.ibm.com/support/knowledgecenter/SSMNED_v10cloud/com.ibm.apic.install.doc/ri_gw_download_install.html) the DataPower rpms from your reserved instance.
- [Install DataPower](https://www.ibm.com/support/knowledgecenter/SS9H2Y_10.0/com.ibm.dp.doc/virtual_forlinux.html?view=kc) on your RHEL VM. In order to do this along with the pre-reqs I used the following commands:
```bash
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install schroot ipvsadm telnet
yum install idg_cloud1.10011.common.x86_64.rpm idg_cloud1.10011.image.x86_64.rpm
```
## Set up link endpoint
- Create a [link endpoint](https://cloud.ibm.com/docs/satellite?topic=satellite-link-location-cloud) pointing to the API Connect Gateway management endpoint (usually port 3000)
## Configure DataPower for API Connect
- Follow the [steps to configure your DataPower](https://cloud.ibm.com/docs/apiconnect?topic=apiconnect-ri-reg-gwy) for use with API Connect.
- For the certificates, in order to avoid a hostname mismatch create a self-signed keypair for the management interface for the hostname generated for your link endpoint.
## Configure Certificate Manager service
- If you don't already have one, create a [Certificate Manager instance](https://test.cloud.ibm.com/catalog/services/certificate-manager)
- Ensure API Connect Reserved Instance is [authorised through IAM](https://www.ibm.com/support/knowledgecenter/SSMNED_v10cloud/com.ibm.apic.install.doc/ri_gwy_certs_auth_svc.html?view=kc) to access this certificate manager instance.
## Add Remote gateway to your reserved instance
- [Register your gateway](https://www.ibm.com/support/knowledgecenter/SSMNED_v10cloud/com.ibm.apic.install.doc/ri_gwy_reg.html) in your API Connect Reserved Instance, filling in the details as follows:
- **Management endpoint** - enter the full URL and port generated by IBM Cloud Satellite for the Link Endpoint prefixed with https://
- **Certificate** - the certificate to present for the mutual TLS communication with the Gateway management
- **CA bundle** - the certificate in certificate manager to use to verify the gateway management endpoint (either your CA or the certificate itself)
- **Base URL** - the endpoint you want APIs to be called through - should map to the **API gateway address** configured in the API Connect Gateway service either directly or through a load balancer.
---
# API Connect v10 Reserved - authentication for CI/CD
URL: https://rickymoorhouse.uk/blog/2021/cicd-workaround/
Date: 2021-03-09
Tags: apiconnect
Currently the v10 Reserved Instance of API Connect doesn't yet have a simple approach for headless use of the CLI toolkit. The following details how to use an IBM Cloud IAM bearer token with the API Connect CLI and REST API in a headless environment such as a CI/CD pipeline.
For interactive use of the API Connect CLI, you can login using the `--sso` option, retreive an api key with your browser and provide that to the CLI for example:
```bash
apic-slim login --server {apic-api-endpoint} --sso
```
However if you want to use the CLI in a non-interactive context such as a CI/CD pipeline you need to retrieve an IBM Cloud IAM Bearer token for the toolkit to use. This can be obtained using `ibmcloud iam oauth-tokens` and then placed in `~/.apiconnect/token` for the `apic` CLI to use.
The token file needs to contain:
```yaml
{apic-api-endpoint}/api: |
refresh_token: ""
access_token: {access_token}
```
This can be done programmatically using something like this:
```bash
ibmcloud iam login --apikey {api-key}
ic iam oauth-tokens | sed 's/IAM token: Bearer /api.9a6e-bd639816.us-south.apiconnect.cloud.ibm.com\/api: |\n refresh_token: ""\n access_token: /' > ~/.apiconnect/token
apic orgs --my --server {apic-api-endpoint}
production [state: enabled] https://api...apiconnect.cloud.ibm.com/api/orgs/9123ae60-427c-4997-8a6b-ddd75b169bfb
test-porg [state: enabled] https://api...apiconnect.cloud.ibm.com/api/orgs/b73708ea-a7b5-4d27-b562-80767e0b238e
```
## Invoking the API Connect REST APIs
To invoke the [API Connect REST APIs](https://apic-api.apiconnect.ibmcloud.com/v10/) in Reserved Instance v10, you can use an IBM Cloud IAM token which can be obtained using the `ibmcloud iam oauth-tokens` CLI command or with an API call as detailed in the [IAM API documentation](https://cloud.ibm.com/apidocs/iam-identity-token-api#authentication). This token can then be used as a bearer token to invoke the API Connect REST APIs.
The full process looks like this:
Firstly use your IBM Cloud API key to retrieve an IAM token
```bash
curl -X POST \
"https://iam.cloud.ibm.com/identity/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
--data-urlencode "apikey=[your api key]"
{"access_token":"[access token would be here]","refresh_token":"not_supported","token_type":"Bearer","expires_in":3600,"expiration":1615370557,"scope":"ibm openid"}
```
Then take the value of the access_token and use it to call the API Connect API e.g.
```bash
curl https://{{ api_host }}/api/orgs \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [access_token]
{
"total_results": 2,
"results": [
{
"type": "org",
"org_type": "provider",
...
}
]
}
```
---
# Monitoring API Connect - 2020 update
URL: https://rickymoorhouse.uk/blog/2020/monitoring-apic/
Date: 2020-11-09
Tags: apiconnect, monitoring, trawler
Even though a lot has changed within the API Connect product and the types and numbers of stacks we're running since I first posted an overview of [monitoring API Connect](/apic/monitoring/) , the main areas we monitor haven't.
We are still using [Grafana](https://grafana.com) as a central location for dashboarding and analysing data across different data sources but some of the tools we're using to collect the data have changed. Having access to all the data in a single UI is really powerful, especially when troubleshooting or investigating events across the systems, being able to identify correlations between data from external load balancing, response times parsed from logs and pod utilisation metrics can really help narrrow in on specific components and how they impact the wider solution.
## Metrics

For metrics we're making use of the IBM Cloud Monitoring with Sysdig to gather metrics from across the kubernetes deployment, including metrics from kubernetes itself and recognisable container applications such as nginx. We also supplement this with our own custom metrics exporter, [Trawler](https://github.com/ibm/apiconnect-trawler), which we built for API Connect to extract key application specific data and expose them to a prometheus compatible monitoring tool or send them to graphite. Examples of data gathererd are counts of objects within API Manager and DataPower and analytics call counts. For endpoint and availability monitoring we are continuing to use [Hem](https://github.com/rickymoorhouse/hem) which is a simple python application to call HTTP(s) endpoints and send the metrics to our graphtie stack. All of these then come together to view within our grafana dashboards - and to be used within new exploratory dashboards whilst problem solving as needed.
## Logging

For our logging infrastructure, we continue to use [Elastic](https://elastic.co/), making use of the filebeat agent within our clusters to gather and tag the container logs, then some custom parsing in logstash to parse out the significant elements from the different logs so that we can easily correlate these with events going on in the system. A lot of the time this data is then viewed in timeseries graphs within grafana, but also linked to Kibana views to dig deeper in the logs themselves.
---
# Trawler - Metric gathering for API Connect
URL: https://rickymoorhouse.uk/blog/2020/trawler-metric-gathering-for-api-connect/
Date: 2020-06-02
Tags: apiconnect, monitoring, trawler
As part of our work in running and monitoring our API Connect cloud deployments we've built some of our own tooling to assist with monitoring what is going on within the deployments. Trawler is one of these items which is used to gather metrics from a Kubernetes based deployment of API Connect.
Trawler runs within kubernetes alongside API Connect and identifies the API Connect components and exposes metrics to prometheus (or other compatible monitoring tooling)
This data can then be used to feed into dashboards such as this one in Grafana:

Trawler is open-source and [available on github](https://github.com/ibm/apiconnect-trawler) and [docker hub](https://hub.docker.com/repository/docker/rickymoorhouse/trawler) - See the [installation guide](https://github.com/IBM/apiconnect-trawler/blob/main/docs/install.md) for more information on using trawler for yourself.
The kind of metrics that trawler collects are currently as follows:
### Management subsystem:
- API Connect version information (apiconnect_build_info)
- Total users (apiconnect_users_total)
- Number of provider_orgs (apiconnect_provider_orgs_total)
- Number of consumer orgs (apiconnect_consumer_orgs_total)
- Number of catalogs (apiconnect_catalogs_total)
- Number of draft products / apis (apiconnect_draft_products_total / apiconnect_draft_apis_total)
- Number of products / apis (apiconnect_products_total / apiconnect_apis_total)
- Number of subscriptions (apiconnect_subscriptions_total)
### DataPower subsystem:
- TCP connection stats (datapower_tcp...)
- Log target stats: events processed, dropped, pending (datapower_logtarget...)
- Object counts e.g. SSLClientProfile, APICollection, APIOperation etc. (datapower_{object}_total)
- HTTP Stats (datapower_http_tenSeconds/oneMinute/tenMinutes/oneDay)
### Analytics subsystem
- Cluster health status (analytics_cluster_status)
- Number of nodes in the cluster (analytics_data_nodes_total/analytics_nodes_total)
- Number of shards in states - active, relocating, initialising, unassigned (analytics_{state}_shards_total)
- Number of pending tasks (analytics_pending_tasks_total)
---
# Trawler
URL: https://rickymoorhouse.uk/projects/trawler/
Date: 2020-06-02
Tags: trawler
Trawler is a metric gathering tool for IBM API Connect deployments, built to monitor Kubernetes-based API Connect cloud deployments.
It runs alongside API Connect in Kubernetes and identifies API Connect components, exposing metrics to Prometheus or other compatible monitoring tooling. The data feeds into dashboards such as Grafana for visualization.
- [GitHub Project](https://github.com/ibm/apiconnect-trawler)
## Metrics Collected
### Management Subsystem
- API Connect version information (apiconnect_build_info)
- User and organization counts (users, provider_orgs, consumer_orgs)
- Catalog and product/API counts
### DataPower Subsystem
- TCP connection stats
- Log target stats (events processed, dropped, pending)
- Object counts (SSLClientProfile, APICollection, etc.)
- HTTP statistics
### Analytics Subsystem
- Cluster health status
- Node and shard counts
- Pending tasks
## Related Blog Posts
---
# View API Error detail
URL: https://rickymoorhouse.uk/blog/2018/view-api-error-detail/
Date: 2018-04-17
Tags: apiconnect
To view the details of the steps in an API in Analytics to assist in debugging you can do the following:
[](/images/viewing-api-detail.gif)
---
# Automatically publish your API when you push to github
URL: https://rickymoorhouse.uk/blog/2015/automatically-publish-your-api-when-you-push-to-github/
Date: 2015-12-12
Tags: apiconnect
*Updated 11th October 2016 for API Connect*
In less than half an hour I could update my project to automatically publish my API in IBM API Connect - Here's the steps...
Sign up for [API Connect](https://console.ng.bluemix.net/catalog/services/api-connect/) through Bluemix by creating an API Connect service instance - if you don't already have a Bluemix account you can sign up for a free trial account.
Install and configure the new toolkit CLI - replacing eu with au or us if you chose a different bluemix region:
```bash
npm install -g apiconnect
apic config:set server=eu.apiconnect.ibmcloud.com
apic login
```
Create a product definition for your API:
```bash
apic create --type product --title "Travel Information" --apis product.yaml
```
Adjust the product definition as needed in your favourite editor
Add the x-ibm-configuration extensions to your swagger document to configure what happens when someone calls the API - in my case invoke the backend API
```yaml
x-ibm-configuration:
enforced: true
phase: realized
testable: true
cors:
enabled: true
assembly:
execute:
- invoke:
title: invoke
target-url: ''
```
Now switch over to your CodeShip account, load your project and go to the Deployment section of your project.
Add a custom script option and confiigure the following script (adding your details as needed):
```bash
npm install -g apiconnect
apic config:set server=eu.apiconnect.ibmcloud.com
apic login -u -p
apic config:set organization=
apic push docs/swagger.yaml
apic stage --catalog=sb docs/travel-information.yaml
apic publish --catalog=sb docs/travel-information.yaml
```
Commit and push to your repository and your updated API will be pushed to API Management! - [Here is my example API](https://developer.beta.apim.ibmcloud.com/hirickymoorhousecouk/sb)
If you don't already have a CodeShip account you can [sign up to CodeShip](https://codeship.com/registrations/new) with your github account and create link in your github repository. You can then set up the tests and deployment steps in the project settings.