Gluing the Dissected: API-Orchestration mimics Maintenance Flow
Ahmed Rezika, SimpleWays OU
Posted 7/3/2025
This kind of mental alchemy — where software mirrors workflow in maintenance— doesn’t just clarify both worlds; it gives us the upper hand to navigate and design them better. In both the world of maintenance and the world of software, abstraction isn’t just a design choice — it’s a lifeline. It’s what shields us from drowning in complexity, so we can focus on doing what matters most. A technician doesn’t need to understand the entire procurement or planning processes to execute a work order. Everyone sees just enough of the system to act with confidence – What is “enough” need to be defined. That’s abstraction. And in modern systems, APIs are how we build that focus and clarity.
In traditional maintenance programs, abstraction was achieved through roles, forms, and step-by-step workflows. In today’s software systems, we orchestrate that same clarity using APIs — clean interfaces between messy layers. In the previous article, From UI to Backend: A Maintenance App Dissection [1], we laid all the parts on the table: UI, logic, backend, data/sheet. Now it’s time to glue those pieces back together with analogy to Maintenance — elegantly, intentionally, and, yes, with a pinch of AI.
What happens when you combine an API-orchestrated maintenance system with a single endpoint to an AI engine? Suddenly, your app can do more than connect — it can understand, summarize, and predict. And the best part? You don’t need a new backend, a full ML -Machine Learning- pipeline, or a team of data scientists. Sometimes all it takes is one API call.In this article, we’ll explore how that “gluing” process works — both in manual maintenance workflows and in modern app development. We’ll examine how abstraction shows up in everyday tasks, and how it’s mirrored in the way we build apps with APIs. We’ll look at how internal and external APIs and Teams work. Then we’ll see a demo how an AI Agent API can inject intelligence into even the simplest apps, and why understanding these layers is essential to building a coherent, maintainable system — even if you’re starting with nothing more than a script, a spreadsheet, an API and a vision.
Section 1: What Is Abstraction — and Why It Matters
Abstraction, in both maintenance programs and digital systems, is what lets individuals operate confidently without being buried in context they don’t need. It’s not about secrecy — it’s about focus, communication and flow.
In a traditional maintenance workflow:
- The operator observes an issue and submits a request — often through a form or entry point designed to be fast and focused.
- The planner receives that work request. Ideally, they review it and make a decision based on the info provided.
But in reality? Sometimes, what’s written isn’t enough.
Maybe it’s vague. Maybe it sounds urgent but isn’t. Or it might be a symptom of something bigger.
So the planner reaches back — confirms with the operator, assigns someone to check field conditions, or even inspects the asset personally.
That’s not a failure of abstraction — that’s the system flexing where it needs to. - The technician still benefits from abstraction. They don’t need the conversation history — just the approved task, parts, and instructions.
- The analyst or auditor later sees performance data, cost history, and root cause codes — not the friction it took to clarify or schedule.
So while abstraction exists, it’s not a rigid wall — it’s more like a filter. It lets most tasks flow cleanly, but allows for deeper interaction where human insight is essential.
In Apps and APIs:
Software systems adopt the same principle:
- A frontend UI submits data via an API call — it doesn’t need to know where the data goes or how it’s processed.
- The API receives a request and routes it to the proper logic: validation, storage, notification, scheduling.
- A mobile app can call GET /workorders?assignedTo=me — and it receives a filtered, formatted list. It doesn’t load the entire task history or decision tree.
- An AI tool plugged into the system might see only selected rows from a sheet to summarize or analyze — not the full application state.
APIs are the abstraction layer. They expose a clean interface that hides the complexity behind the scenes — not to lock others out, but to allow each component to work in isolation and at speed.
The Limits of Absolute Abstraction:
While abstraction empowers focus, over-abstraction can create friction — especially in maintenance, where context is fluid and urgency varies minute by minute.
Many high-end CMMS\ERP systems fall into this trap. By enforcing strict interfaces between roles and rigid workflows through their apps, they disconnect the user from judgment, and the system from reality. A planner might receive a perfectly structured work request — but still need to find answers for:
- “Was this a one-time thing, or has it happened all week?”
- “Are we in a production crunch or can this wait?”
- “Did you check the pressure valve before raising this?”
When apps assume that the input tells the whole story, they lose the human edge — the improvisation, verification, and flexibility that frontline maintenance work thrives on.
That’s why building a digital system — even a simple one — must leave room for human dialogue, exception handling, and manual overrides. Abstraction isn’t about removing the human; it’s about letting the human act where they’re most needed, without being bogged down where they’re not.
In your own apps, this might mean:
- Letting a planner leave a note or request clarification before approving a WO
- Allowing operators to edit or cancel their requests
- Exposing some internal process states through optional views, not hiding them completely
Why This Matters:
“You can’t scale a system that forces everyone to handle everything — but you also can’t build one that pretends that context doesn’t matter.”
Abstraction gives structure — it reduces noise, minimizes decision fatigue, and helps people focus. But in maintenance, clarity without context can be dangerous. If abstraction becomes too rigid, it frustrates the human judgment it’s meant to support.
The goal isn’t only to hide complexity — it’s to manage it intelligently. In a maintenance program:
- Technicians should focus on tasks, not paperwork.
- Planners should filter information — but also loop back when clarity is needed.
- Apps should guide workflows — but leave room for exceptions and human escalation.
- APIs should cleanly divide responsibilities — but also support insight on demand.
Abstraction is a frame, not a cage.
When designing or digitizing a maintenance system — even with something as simple as Sheets and Apps Script — honoring this principle means the difference between efficient flow and functional frustration.
Section 2: Mirrors in Design: Internal APIs and In-House Teams vs. External Interfaces and Contractors
The abstraction we had spoken about helps each part of the system to focus its effort and attention on their own functions. Same approach serves well the relation with external services and service providers but within different context.
External APIs are interfaces to third-party services or platforms that allow us access external applications, including data, functionality or wisdom of AI agents. AI agents might use these APIs to perform tasks such as retrieving information, updating records, or triggering actions on behalf of users based on the prompt and data based to them
Characteristics of External APIs:
Scope: Publicly or selectively exposed to external developers or applications outside the organization.
Purpose: Enable integration with external ecosystems, expanding app capabilities by leveraging third-party services.
Security: Requires robust authentication and authorization (OAuth, API keys) to protect user data and control access. AI agents must obtain credentials and user consent to act on their behalf.
Integration Complexity: Needs careful versioning, backward compatibility, and comprehensive documentation to support diverse external clients, including AI agents.
Examples: Payment gateways (Stripe, PayPal), social media APIs (Facebook, Twitter), mapping services (Google Maps), or connecting AI agents to tools like Mail servers and Zoom via APIs.
AI Agent Specifics: AI agents act as autonomous or semi-autonomous clients that interact with external APIs to fulfill user requests intelligently. They require mechanisms to authenticate, handle authorization scopes, and sometimes progressively request more permissions for sensitive actions. Unlike simple API clients, AI agents may maintain state, adapt to context, and make decisions based on API responses
Internal Teams vs. Subcontractors — An Industrial Maintenance Analogy:
To better understand the distinction between internal APIs and external APIs, imagine an industrial maintenance program in a large manufacturing plant.
Internal APIs as Interactions Within the Organization teams
In this analogy, internal APIs are like the maintenance teams and technicians employed directly by the company. These teams handle routine inspections, repairs, and upkeep of equipment within the plant. They have:
– Deep knowledge of the plant’s machinery and processes (analogous to internal APIs having intimate knowledge of internal systems and data).
– Direct communication and coordination with other internal departments, such as production or quality assurance (like internal APIs connecting various internal services).
– Access to sensitive or proprietary information about the equipment and operations that the company does not share externally (similar to internal APIs not being exposed to the public internet).
– Flexible workflows and rapid response times because they operate within the company’s trusted environment (reflecting how internal APIs can be optimized for efficiency and security without external constraints).
– These internal teams work closely together, sharing information and tools seamlessly to keep the plant running smoothly—just as internal APIs enable different software components or microservices[2] to collaborate efficiently within an organization.
External APIs as Subcontractors Performing Specialized Tasks
By contrast, external APIs are like subcontractors or specialized vendors hired to perform specific maintenance tasks that the internal team cannot or should not handle. For example, the company might hire an external firm to:
– Service highly specialized machinery requiring unique expertise.
– Provide emergency repairs when internal capacity is exceeded.
– Supply parts or services that are not available in-house.
These subcontractors:
– Operate outside the company’s direct control but must follow strict contracts and security protocols (similar to how external APIs require authentication, authorization, and careful access control).
– Have limited access to the plant’s internal data and systems, only what is necessary to perform their tasks (like external APIs exposing only specific, controlled functionality).
– Need clear interfaces and communication channels to coordinate with the internal teams and avoid disruption (analogous to well-documented, standardized API endpoints and protocols).
– May have different priorities, schedules, and workflows that require careful integration and monitoring (reflecting the complexity of managing external API dependencies, rate limits, and error handling).
Why This Analogy Matters:
We understand new systems best when we see them through the lens of what we already know. Drawing parallels between APIs and maintenance services — internal vs external, visible vs abstracted — isn’t just wordplay; it’s how we demystify complexity and plan communication. Just as modern machine learning models like Transformers [3] expanded their power by learning to attend to context, we too unlock deeper understanding when we reflect the unfamiliar on the familiar. This kind of mental alchemy — where software mirrors service contracts, and workflows echo code — doesn’t just clarify both worlds; it gives us the upper hand to navigate and design them better. It’s the same principle that makes RCM analysis powerful: by understanding how each component fits into a bigger system, we make smarter, more strategic decisions.
Efficiency and Security: Just as it would be inefficient and risky to have subcontractors roam freely inside the plant without boundaries, external APIs must be carefully managed to protect sensitive data and ensure reliable operation.
Specialization and Scalability: Internal teams focus on core operations, while subcontractors bring specialized skills and capacity. Similarly, internal APIs optimize internal workflows, while external APIs extend capabilities by integrating third-party services.
Clear Boundaries and Interfaces (Communication): Both internal teams and subcontractors rely on clear communication protocols and defined responsibilities, just as internal and external APIs require precise interface definitions and security controls.
Hands-On: AI via API: Injecting Intelligence into a Simple Maintenance App
“One API call can bring the power of a billion-parameter model into your app.”
That’s not just a bold promise — it’s a working reality.
Today, just like APIs help abstract and orchestrate data movement, they also offer a new level of abstraction: decision-making intelligence. And that leap started not in a maintenance department — but in a breakthrough AI published paper.
The Shift: From RNNs to Transformers
In 2017, machine learning models for text relied on sequential attention to understand language word by word. But in 2018, a landmark paper titled “Attention is All You Need” [3] by Vaswani et al. introduced the Transformerarchitecture, shifting the focus from word sequence to pattern awareness. This allowed models to attend to multiple parts of input simultaneously — dramatically improving focus, generalization, and speed.
The Power of One API Call: AI Meets App Script
Here’s the power: You don’t need to train a model or build a complex AI engine. Just one call to the AI Agent APIcan give quick recommendations in case of warning or critical situations that is blending asset data with inspector notes. We could have programmed rule-based recommendations based on the case and equipment but it would be a lot of if-else scenarios and will always not look to the current inspector comments.
Moreover, it doesn’t require a backend overhaul. In the maintenance app we dissected in the previous article[1], I added a simple script that:
- Lets the user enters a new record.
- In case there’s a warning or a critical situation, The option to get AI advice pops up.
- The API call to an AI-Agent returns a summary of the situation and action suggestions in real-time.
Example Code Snippet (Simplified)
It was possible by adding one command -as below- that assembles the custom crafted prompt with the asset records and the API key obtained from an AI Agent as open.ai. The prompt serves to tell the AI agent what to do with the data of the asset, what you look for and so on. The talent lies in tuning the prompt to provoke a full answer that contains all what you need as support. Also selecting and passing the correct data in a readable format for the AI Agent facilitates and expedites this process and make it feasible. I can say mouth-fully that Prompt Engineering was one of the best skills that I mastered recently.
Explore the app here
Conclusion: Analogy between Maintenance and App Architecture: From Chaos to Cohesion
Abstraction alone isn’t enough. Real maintenance work often requires judgment, communication, and soft edges. Systems that over-abstract risk creating resistance — the very opposite of what digital transformation should do. That’s why successful maintenance systems need smart abstraction: clear roles, focused views, but with the freedom to reach across layers when needed. This serves perfect when interacting with external teams or APIs.
And now, with a single API call, even intelligence itself can be abstracted and integrated. By tapping into the power of large language models — like OpenAI’s GPT — planners can instantly analyze, summarize, and act on work request history, right inside the app they already use. No new interface, no backend overhaul — just one well-placed function call.
So whether you’re gluing microservices together with Apps Script or adding AI insight to a Google Sheet, the message is the same:
You don’t need a massive system to orchestrate smart maintenance.
You need a smart way to connect the parts.
In the next article, we’ll step back and ask:
What comes first — the maintenance program or the maintenance app?
Because designing software is one thing. But designing it around the right process? That’s where real transformation begins.
Must-Know Jargon
🔹 Abstraction: The practice of hiding complexity behind a simple interface. In maintenance apps, abstraction means showing each actor (planner, technician, etc.) only what they need to see — not the whole workflow engine underneath.
🔹 API (Application Programming Interface): A digital contract between systems that defines how they communicate. APIs are the building blocks that allow apps to exchange data reliably, without human back-and-forth.
🔹 Apps Script: A lightweight scripting platform by Google that automates workflows in Sheets, Forms, and Docs. It acts like a programmable backend for non-developers.🔹 Transformer (AI Architecture): A groundbreaking AI model introduced in 2017 that changed how machines understand patterns in language. It focuses on the most relevant parts of input, enabling faster and smarter analysis.
References
1. From UI to Backend: A Maintenance App Dissection [ ,Ahmed Rezika, 06 May 2025, MaintenanceWorld Magazine, https://maintenanceworld.com/2025/06/05/from-ui-to-backend-a-maintenance-app-dissection/
2. What Is Microservices Architecture, Wallarm / Wallarm Learning Center, https://lab.wallarm.com/what/what-is-microservices-architecture-2/
3. Attention Is All You Need, Ashish Vaswani et al, Submitted on 12 Jun 2017 (v1), last revised 2 Aug 2023 (v7), Cornell University
Related Articles
How to Fix the 70/30 Phenomenon
Zen and the Art of Managing Maintenance
Why do maintenance improvement initiatives fail to deliver? (Hedgehog or Fox?)
Why Maintenance Improvement Efforts Fail
TPM and RCM: Whirled Class
Where Do Maintenance Professionals Come From?
