DEV Community: AbdulmalikAlayande

Realtime from First Principles, Part 2: WebSocket and The WebSocket Protocol

AbdulmalikAlayande — Thu, 03 Sep 2026 19:40:06 +0000

WebSocket is a communication protocol that enables full-duplex, bi-directional communication between a client and a server over a single, persistent connection built on top of TCP. Unlike the request-response model that defines regular HTTP traffic, where the client must always initiate every exchange and the server can only reply when asked, WebSocket keeps the connection open once it is established, so either side, the client or the server, can send data to the other at any moment, without waiting for a request first.

Before going further, it helps to be clear on what full-duplex actually means, since it is easiest to understand next to its two relatives: simplex and half-duplex. All three describe the direction data is allowed to flow between two devices that are communicating with each other.

Simplex communication only allows data to move in one direction, from a sender to a receiver, and never the other way. Think of a keyboard or a mouse sending input to a computer. The keyboard tells the computer what key was pressed, but the computer never sends anything back to the keyboard through that same channel. Data flows one way, permanently.

Half-duplex communication allows data to move in both directions, but never at the same time. Only one side can send at any given moment, and the other side has to wait its turn. A walkie-talkie conversation is the clearest everyday example of this. When one person is speaking, the other person has to stay quiet and listen, and only after the first person finishes and signals that they are done, usually by saying something like "over," can the second person start talking. Both sides can send and receive, but taking turns is mandatory.

Full-duplex communication allows data to move in both directions at the same time, with neither side needing to wait for the other. A regular phone call is the clearest example of this. Both people on the call can speak and listen at once, and if you interrupt the other person mid-sentence, they still hear you, because both directions of the conversation are open simultaneously. This is exactly the behavior WebSocket gives to a client and a server. Once the connection is open, the server does not have to wait for the client to ask before sending data, and the client does not have to wait for the server to finish before sending its own message. Both sides can talk over the same open connection whenever they need to.

WebSocket came about as a direct answer to the limitations already discussed with HTTP-based workarounds like polling, long polling, and HTTP streaming in the first series. The design intent was to give developers something closer to raw TCP itself, a connection where data can flow freely in both directions with minimal overhead. At the same time, they could not hand developers pure, unmodified TCP, because TCP on its own knows nothing about how the web works. It has no concept of an HTTP-based origin, no built-in way to distinguish one message from another, and no knowledge of the security assumptions browsers already rely on. So WebSocket layers a small number of abstractions on top of TCP, just enough to let it work correctly within the existing web platform, without reintroducing the request-response overhead it was designed to escape.

The WebSocket Protocol

At a high level, the WebSocket protocol has three phases. It begins with an opening handshake, where a regular HTTP connection is upgraded into a WebSocket connection. This is followed by the data transfer phase, where the actual back-and-forth communication happens, with both the client and the server free to send messages whenever they need to, in either direction. Finally, there is a closing handshake, where either side signals that it wants to end the connection, and both sides agree to close it cleanly. Each of these phases is worth walking through in detail, starting with how the opening handshake actually works.

Realtime from First Principles, Part 1: How the Web Learned to Fake Realtime

AbdulmalikAlayande — Tue, 25 Aug 2026 16:55:49 +0000

During the 1990s, the web grew into the dominant way people exchange information, and browsers kept adding new features as more and more people got comfortable browsing. By the 2000s, the first attempts at realtime web apps started showing up, apps trying to feel responsive and interactive instead of the usual static webpage. But realtime was hard to pull off then, and slower than anything you would have recognize today, because it was being built by hacking HTTP-based technologies that were never designed for that kind of work in the first place.

The Origins of HTTP

To understand why hacking HTTP-based technologies was even necessary, it helps to go back to where HTTP came from, In 1989, Tim Berners-Lee was working at CERN and grew frustrated with how hard it was to pull information off computers running different software from each other. Out of that frustration came a project called WorldWideWeb: a web of hypertext documents that browsers could view over the internet using a client-server setup. That idea spread fast, and the first websites for everyday use appeared around 1993 to 1994.

To build the web, Berners-Lee combined hypertext with the internet and produced three foundational pieces:

HTML: a markup language used to structure and present content on the web.
URI: a unique address assigned to every resource on the web.
HTTP: a way to request and receive resources on the web.

That very first version of HTTP, later called HTTP/0.9, was about as minimal as a protocol can get. A request was one line, starting with the only method that existed then, GET, followed by a path. The response was raw hypertext, with no headers, status codes, or versioning, and the connection closed once the response was delivered.

As interest in the web grew, browsers and servers started adding new features to the HTTP protocol, but a new problem began, new features added to the HTTP protocol was not coordinated, so there were different implementations of the HTTP/0.9, these implementations started drifting apart which led to the compatibility issues between different softwares that need to communicate with each other.

The Rise of JavaScript

While HTTP was maturing, something else was happening, "The Browser Wars - browsers like Internet Explorer and Netscape Navigator working hard to out-feature each other", it was in that competitive climate, in 1995, that Netscape hired Brendan Eich to add scripting to Netscape Navigator, and JavaScript was born. It started out doing almost nothing interesting, mostly basic form validation, but it was the first form of dynamism in a web that had until then been completely static. From there it kept getting standardized and adopted everywhere, eventually becoming one of the most important technologies of the web today.

Early Attempts at Realtime

With the existence of HTTP, HTML and now JavaScript, real web applications started to emerge, and the first serious attempts and efforts to make the web feel realtime came along in the late 90s. Two design models dominated that effort: AJAX and Comet.

AJAX (Asynchronous JavaScript and XML)

Ajax is a way of exchanging data with a server in the background and updating parts of a page without forcing a full reload. It was not a single technology on its own, it uses many existing technologies to achieve its realtime feel. It uses:

HTML and CSS for the UI
Document Object Model (DOM) for dynamic updates
XML/JSON for the data format itself
and most importantly the XMLHttpRequest object which allows JavaScript to make HTTP requests behind the scenes.

Ajax changed something structurally about how the classic web model worked. In the web model before AJAX, almost every user action fired off an HTTP request, and the server always sends back an entirely new HTML page in response. Ajax introduced something new between the server and the client - the AJAX engine. The client, instead of loading a fresh page each time it gets new contents, it loads the AJAX engine once and the engine takes over the job of polling the server in the background and asynchronously updating parts of the UI that needs updating.

Comet

The comet model which came a bit later than AJAX, is a web application design model that allows the server to continuously push updates to the browser, Similar to Ajax, it asynchronously communicates with the browser, unlike Ajax, comet opens a long lived http connection that allows the server to continuously push updates to the client (browser), whenever they are available, without the client explicitly requesting them. Comet itself was also not a single technology, it was an umbrella covering a couple of approaches that are used to achieve the realtime feel. Comet uses two approaches:

Long Polling: A smarter version of normal polling, where instead of the server replying immediately with "nothing yet" when there is no new data available, it holds the connection open for as long as required, until either new data actually shows up or a timeout hits and then the client immediately fires off another request to the server to keep the cycle going.
HTTP Streaming (HTTP server push): A data transfer technique that allows a web server to continuously send data to a client over a single HTTP connection that remains open indefinitely. Whenever there's an update available, the server sends a response, and only closes the connection when explicitly told to do so. It is similar to Long Polling, just that it goes further still by keeping a single connection indefinitely.

The Cost of Hacking HTTP

By this point AJAX and Comet had already opened the door to dynamic, realtime-feeling web apps, and in a smaller way, both are still used today. But they were never solved the problem cleanly, because underneath all of it was still HTTP, and HTTP was built from the ground up to serve hypermedia resources in a request-response fashion: the client asks for something, the server responds, and that exchange is the complete transaction. It was never designed to handle high-frequency or ongoing client-server communication, or with the ability to react instantly to changes on either side. So, hacking HTTP-based technologies to emulate realtime web brought about different kinds of problems, and some of them are discussed below.

Limited Scalability

Take HTTP polling for example, which is sending requests to the server at fixed intervals to check whether new data is available. Polling very frequently means you get always get new data, but that comes with a problem, because high polling frequencies result in increased network traffic and server demands, which obviously does not scale well, especially as the number of concurrent users increases. Polling less frequently can reduce the network traffic and server demands, but that means handing the client information that has already gone stale by the time it arrives, which defeats the purpose of chasing realtime behavior in the first place.

A better option would be Long Polling, but it also comes at its own cost because keeping thousands of "held-open" requests alive simultaneously demands a lot of server resources, since each one is still, at bottom, a connection the server has to maintain and eventually close and reopen.

Unreliable Message Ordering and Delivery Guarantee

A client can have multiple requests in flight to the server at the same time, and because network conditions are unpredictable, there is no guarantee that requests will arrive at the server, or response will get to the client in the specific order they were sent. On top of that, a server might send a response that never reaches the client, whether due to a network hiccup or a browser issue, and unless the application has built some kind of receipt confirmation on top of HTTP itself, a message can simply vanish without either side realizing it.

No Bidirectional Streaming

Another limitation of HTTP is that it does not have the concept of bidirectional streaming. It is a request/response protocol at its core, which means it was never built to let client and server hold an always-on, two-way conversation across a single connection. You can fake this by opening two separate HTTP connections, one for each direction, but now the server has to maintain double the connections to serve what is functionally one client, and that overhead compounds badly as your user count grows.

Higher Latency

Setting up a new HTTP connection requires a couple of handshakes involving several round-trips between the server and the client, before any useful data is sent, couple with the fact that HTTP requests are sequential by nature: the next request can only go out after the response to the current request is back. Network delays might also be a thing, depending on the network conditions at that moment. String enough of these together and the cumulative latency becomes a real problem for anything trying to feel instantaneous.

A better option to avoid higher latency would be HTTP streaming techniques, since they avoid opening new connections repeatedly. But, they are still bound by the overhead of HTTP headers riding along with every message, resulting in increased message size and causing unnecessary delays. In many cases these headers end up outweighing the actual payload being delivered, which is a strange kind of inefficiency when the whole goal is speed.

So every one of these techniques was, at its core, a workaround, and workarounds built on a mismatched foundation tend to produce their own new problems. That was the thread that leads into everything WebSocket was eventually built to fix.

In the next series we will go fully into WebSocket

Building an RPC Server From Scratch in TypeScript

AbdulmalikAlayande — Tue, 25 Aug 2026 16:44:56 +0000

(Inter-Process Communication)[]
(Remote Procedure Calls)[]

Building an RPC Server From Scratch in TypeScript

AbdulmalikAlayande — Tue, 25 Aug 2026 16:27:14 +0000

(Inter-Process Communication)[]
(Remote Procedure Calls)[]

OAUTH2.0 In Action — A Guide To Implementing OAUTH In Apps and Websites.

AbdulmalikAlayande — Fri, 03 Jul 2026 12:44:56 +0000

What is OAUTH
A trip to OAUTH1.0Ville
What is OAUTH2.0
Examples of OAUTH Technology
OIDC
Hands-on Implementation with Microsoft Entra ID

What is OAUTH

OAUTH is a technological standard that allows you to authorize one app or service to sign in to another without divulging private information, such as passwords.

OAUTH stands for Open-Authorization, not Authentication. Authentication is a process that verifies your identity, although OAUTH involves identity verification, its main purpose is to grant access to connect you with different apps and services without requiring you to create a new account.

How Does OAUTH Work

OAUTH uses access tokens, and this is what makes OAUTH secure to use. An access token is a piece of data that contains information about the user and the resource the token is intended for. A token will also include specific rules for data sharing.

For example, you want to share your photos from Instagram with Kyrier — An intelligent email platform built for professionals who refuse to let their inbox run their day, but you only want Kyrier to access your profile image. Kyrier does not also need to access your direct messages or friends list. Instagram issues an access token to Kyrier to access the data you approve (your profile image in this case) on your behalf. So an access token will only allow Kyrier to access your profile image, not even other photos on your page. There may be rules governing when Kyrier can use the access token, it might be for a single use or for recurring uses, and it always has an expiration date.

A trip to OAUTH1.0Ville

Welcome to OAuth1.0Ville. Please keep your hands inside the vehicle.

This is where OAuth started. It was built only for websites, back when "an app" meant a web page and nothing else. Although it worked, it had a lot of problems:

Only three authorization flows (2.0 has six)
No real plan for mobile or modern apps
A scaling problem it never solved

It also makes you cryptographically sign every single request, which does not sound like a problem until you are the one debugging why your signature does not match at 2am.

Today almost nobody builds with OAuth1.0. OAuth2.0 is the new standard everyone uses and agrees with.

What is OAUTH2.0

OAuth 2.0 is the version you actually want. Think of it as OAuth 1.0 after it hit the gym, got a haircut, and stopped making your life difficult.

It was a full redesign, not a patch. Several big tech companies threw in feedback, and the goal was simple: completely replace 1.0 and never speak of it again.

Why everyone uses it:

Works for both apps and websites, not just websites
Faster and easier to implement
Actually scales
Gives you six authorization flows to pick from, so the handshake fits what you are building (server app, mobile app, machine-to-machine, and so on)

Note: You cannot upgrade OAuth 1.0 to 2.0. They are two different things. A site can technically support both, but that is like keeping a landline next to your smartphone.

Examples of OAUTH Technologies

Say you are using Zoho Cliq as a collaboration tool, and you want to know more about the people you work with, both inside and outside your organization. So you enable integration with LinkedIn, so you can learn more about people as you interact with them, without ever leaving Zoho. LinkedIn uses OAUTH to authorize Zoho, so Zoho can pull the LinkedIn profile details you allow, right inside your Zoho workspace, without you handing over your LinkedIn password.
As a developer, you are most certainly familiar with GitHub, or any other Software collaboration and code hosting tools like BitBucket or GitLab. Say you are using GitHub and You wanted to link CodeRabbit with your GitHub account so it can perform automated code reviews once you push or raise a PR, You go to GitHub through the CodeRabbit website and GitHub asks you to download the app, it would then ask you to authorize a connection with the app using your GitHub identity, a process that would be handled using OAUTH. CodeRabbit can then easily access the repositories you enabled it to access and starts listening for any PR or push events, and start reviewing your codes, without you having to sign in to both services every time.

OIDC (Open ID Connect)

OIDC is an authentication strategy to verify a person's identity, it is similar to OAUTH in that, they both give one application access to another application's resources on behalf of the user they are requesting for. Both OIDC and OAUTH have a role to play in enabling two unrelated apps to share information without compromising user data.

Hands-on Implementation with Microsoft Entra ID

Enough of theory. Let us actually create up an app that can read someone's Outlook mailbox using OAuth 2.0. We will use delegated access, meaning the app acts on behalf of a signed-in user, not as itself.

Note: All OAuth2 providers follow the same flow: redirect the user to authorize, get a code back, exchange that code for tokens, fetch the user profile, then find or create the user and start a session.

Note: Microsoft killed Basic Auth for Exchange Online back in October 2022, and EWS is on life support. In 2026, the only to authorize apps to access data on a users behalf using OAuth 2.0 is through Microsoft Graph, and that is what we will do now.

Step 1: Register your app in Microsoft Entra ID

Go to the Microsoft Entra admin center (portal.azure.com), go to Microsoft Entra ID > App registrations > New registration.

Note: Creating a new app normally is now impossible, you have to join the Microsoft 365 Developer Program

Give it a recognizable name (this is really important)
Pick who can use it (single tenant is fine for now)
Add a Redirect URI. Pick Web if it is a server-side app, or SPA if it is a single-page app. Use something like https://localhost/myapp/ for local testing

Click on register. On the Overview page, copy two things you will need:

Application (client) ID
Directory (tenant) ID

Step 2: Get a secret (or better, a certificate)

Go to Certificates & secrets > New client secret. Copy the Value immediately. It is shown exactly once, then it is gone forever and you will be making a new one. Ask me how I know 😂.

Note: certificates are more secure than secrets for production. For a hands-on demo like this, a secret is fine.

Step 3: Add the permissions you need

Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions.

For reading mail, add:

User.Read
Mail.Read
offline_access (this is the one that gets you a refresh token, do not skip it)

Only ask for what you need. The whole point of OAuth is that you do not grab the entire mailbox when you only want to read it.

Step 4: Send the user to log in (authorization request)

Redirect the user to the authorize endpoint. This is the screen where they log in and approve your permissions:

Nigerian Government Fees API: AI-Powered Public Service Data

AbdulmalikAlayande — Mon, 15 Dec 2025 07:57:22 +0000

This is a submission for the Xano AI-Powered Backend Challenge: Production-Ready Public API

What I Built

I built the Nigerian Government and Public Utility Fees API, a production-ready REST API that provides verified, structured, and traceable information about Nigerian government fees and public utility costs and centralizes the information from multiple Nigerian agencies into one accessible endpoint.

In Nigeria, citizens often struggle to find accurate information about the official cost of services such as:

National Identification Number (NIN) services
WAEC / NECO / JAMB examination fees
Passport and identity-related processes
Electricity tariffs across different DisCos
Other government-regulated public fees

The problem

For most Nigerians, finding accurate government fee information is frustrating. Information is usually scattered across PDFs, outdated websites, or unofficial sources. This API centralizes that data into a clean, developer-friendly backend that can be reliably consumed by applications, chatbots, dashboards, and AI agents.

The Solution

A single API that provides:

90+ verified government fees across 6 categories (Identity, Immigration, Education, Electricity, Transport, Business)
6 official agencies: NIMC, NIS, NECO, JAMB, NERC, UNILAG
Complete documentation with code examples in JavaScript, Python, and cURL
Rich relationship data: Every fee includes category, agency, and official source information
Search & filtering: Find exactly what you need instantly

The API is built with a strong focus on:

official data sources
traceability
maintainability
real-world production usage

Live API URL: https://xmlb-8xh6-ww1h.n7e.xano.io/api:public

API Documentation

The API follows a simple and predictable REST structure.

Core Resources

Categories (e.g. Identity & Management, Education, Electricity)
Subcategories (e.g. NIN, NECO, JAMB, Passport, DisCos)
Fees (individual payable items)
Agencies (government bodies)
Sources (official documents and websites)

Base URL

https://xmlb-8xh6-ww1h.n7e.xano.io/api:public

Authentication

API key via query parameter: ?api_key=YOUR_KEY
Test API Key: nga_b6cf98a60bda43ba8cf54af9dbd87260

Available Endpoints

1. POST /api_key/generate

Generates the API key to be used for accessing the secured endpoints.

Example

curl -X 'POST''https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/api_key/generate' -H 'Content-Type: application/json' --data '{"user_email":"your-email@example.com"}'

2. GET /fees

Retrieve paginated list of fees with optional filtering.
Parameters:

category (optional) - Filter by category name/slug
state (optional) - Filter by state
search (optional) - Search in name and description
page (optional, default: 1) - Page number
per_page (optional, default: 20, max: 100) - Results per page

Example:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees?category=identity&per_page=5'

3. GET /fees/{id}

Get single fee by ID with all relationships.

Example:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees/1?api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260'

4. GET /fees/search

Search fees by name and description (min 2 characters).

Example:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees/search?q=passport&api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260'

5. GET /categories

Get all categories with fee counts.

Example:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/categories?api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260'

6. GET /metadata

Get API statistics and version information.

Example:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/metadata?api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260'

Rate Limits

Currently no rate limits enforced. Request tracking is implemented for future rate limiting.

Response Format

All responses are JSON. Errors follow standardized format:

{
  "code": "ERROR_CODE_TYPE",
  "message": "Human-readable error message"
}

Full documentation: Available in my GitHub repository with complete request/response examples, error handling, and integration guides.

Demo

Example 1: Generate API Key

Request:

curl -X 'POST''https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/api_key/generate' -H 'Content-Type: application/json' --data '{"user_email":"your-email@example.com"}'

Response:

{
    "success":true,
    "api_key":"nga_********************************",
    "message":"API key generated successfully. Please save this key as it provides access to the API."
}

Example 2: Get All Categories

Request:

curl -X 'GET' \
  'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/categories?api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260' \
  -H 'accept: application/json'

Response:

[
  {
    "id": 1,
    "display_name": "Identity & Management",
    "description": "Fees related to national identity systems such as NIN",
    "fee_count": 19
  },
  {
    "id": 2,
    "display_name": "Immigration",
    "description": "Passport and visa related fees",
    "fee_count": 10
  },
  {
    "id": 3,
    "display_name": "Education",
    "description": "NECO, JAMB and related examination fees",
    "fee_count": 45
  }
]

Example 3: Search for NIN Fees

Request:

curl -X 'GET' \
  'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees/search?q=NIN&api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260' \
  -H 'accept: application/json'

Response:

[
  {
    "id": 1,
    "name": "NIN Enrolment (First Time)",
    "amount": 0,
    "currency": "NGN",
    "service_type": "Standard",
    "description": "Initial NIN enrollment is free",
    "category_name": "Identity & Management",
    "agency_name": "National Identity Management Commission",
    "subcategory_name": "NIN",
    "source_name": "NIMC"
  }
]

Example 4: Get Fee Details

Request:

curl -X 'GET' \
  'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees/20?api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260' \
  -H 'accept: application/json'

Response:

{
  "id": 20,
  "name": "Standard Passport 32 Pages (5-Year Validity)",
  "amount": 100000,
  "currency": "NGN",
  "service_type": "Standard",
  "description": "New or Renewal",
  "subcategory": {
    "id": 3,
    "name": "Passport",
    "category": {
      "id": 2,
      "name": "Immigration",
      "description": "Passport and visa related fees"
    }
  },
  "source": {
    "id": 2,
    "name": "Nigerian Immigration Service (NIS)",
    "agency": {
      "id": 2,
      "name": "Nigeria Immigration Service",
      "website": "https://immigration.gov.ng"
    }
  }
}

Code Integration Examples

JavaScript:

const BASE_URL = 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public';
const API_KEY = 'nga_b6cf98a60bda43ba8cf54af9dbd87260';

async function searchFees(query) {
  const response = await fetch(
    `${BASE_URL}/fees/search?q=${query}&api_key=${API_KEY}`
  );
  const data = await response.json();
  console.log(`Found ${data.length} fees matching "${query}"`);
  return data;
}

searchFees('passport');

Python:

import requests

BASE_URL = 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public'
API_KEY = 'nga_b6cf98a60bda43ba8cf54af9dbd87260'

def search_fees(query):
    response = requests.get(
        f'{BASE_URL}/fees/search',
        params={'q': query, 'api_key': API_KEY}
    )
    data = response.json()
    print(f'Found {len(data)} fees matching "{query}"')
    return data

search_fees('passport')

Try it yourself with your API key, see the example provided above!

The AI Prompt I Used

I used Cursor with XanoScript to generate all 5 core endpoints. Here's my main prompt:

Generate 5 Xano API endpoints for a Nigerian government fees API:

1. GET /fees
   - Query fees table with optional filters: category, state, search
   - Include relationships: subcategory, category, agency, source
   - Add pagination: limit (default 50), offset (default 0)
   - Return JSON with data array and metadata

2. GET /fees/{id}
   - Get single fee by ID with all relationships
   - Return 404 if not found
   - Include subcategory, category, source, and agency data

3. GET /categories
   - List all categories
   - Include count of fees in each category
   - Return with display_name and description

4. GET /fees/search
   - Accept 'q' query parameter (required, minimum 2 characters)
   - Search in fee name and description using case-insensitive match
   - Limit to 20 results
   - Include all relationships

5. GET /metadata
   - Return API statistics (total fees, categories, agencies)
   - Include last database update timestamp
   - Return API version number

AI delivered in ~30 minutes:

Complete XanoScript code for all 5 endpoints
Database query structures with joins
Basic input validation
Pagination logic
Error handling with preconditions

Time saved: ~6 hours of boilerplate coding

How I Refined the AI-Generated Code

AI gave me a great starting point, but I had to fix critical bugs and add production features. Here are the key refinements:

Issue #1: Invalid `eval` Syntax - CRITICAL BUG

AI Generated (GET /fees/{id}):

eval = {
  category   : $db.{}
  subcategory: $db.{}
  agency     : $db.{}
  source     : $db.{}
}

The Problem: $db.{} is invalid XanoScript syntax. This caused relationships to fail silently—no error in development, but incomplete data in production.

My Fix:

// Removed invalid eval block
// Used db.get to fetch relationships separately
var $subcategory { 
  value = db.get('subcategories', $fee.subcategory_id) 
}
var $category { 
  value = db.get('categories', $subcategory.category_id) 
}
var $source { 
  value = db.get('sources', $fee.source_id) 
}
var $agency { 
  value = db.get('agencies', $source.agency_id) 
}

// Then nested them properly using var.update
$fee|var.update: { 
  subcategory: {
    ...$subcategory,
    category: $category
  },
  source: { 
    ...$source, 
    agency: $agency 
  }
}

Impact: Relationships now properly included in every response. API went from returning incomplete data to being production-ready.

Issue #2: N+1 Query Performance Problem

AI Generated (GET /categories):

foreach ($categories as $category) {
  // Query fees for EACH category individually - terrible for performance!
  var $fee_count { 
    value = db.query('fees', { 
      where: { subcategory.category_id: $category.id }
    }).count
  }
}

The Problem: If you have 6 categories, this makes 6 separate database queries. Would fail under load.

My Optimization:

// Single query with proper aggregation
var $fee_counts {
  value = db.query('fees', {
    join: { 
      subcategories: { category_id: 'categories.id' } 
    },
    group_by: 'categories.id',
    select: {
      category_id: 'categories.id',
      fee_count: 'COUNT(fees.id)'
    }
  })
}

Impact: Reduced database queries from 6 to 1. Response time improved by ~60%.

Issue #3: Empty Results Bug

The Problem: When calling /fees with no filters, API returned {"items":[],"itemsTotal":0} despite having 87 fees in the database.

Root Cause: The where clause was too restrictive. When optional filters were null, the logical AND conditions were filtering out all records.

My Fix:

// Added explicit null/empty checks for each optional filter
where = (
  ($search_filter == null || $search_filter == '' || 
   $db.fees.name includes? $search_filter || 
   $db.fees.description includes? $search_filter) && 
  ($category_filter == null || $category_filter == '' || 
   $db.category.slug ==? $category_filter || 
   $db.category.name ==? $category_filter) && 
  ($state_filter == null || $state_filter == '' || 
   $db.fees.meta.state ==? $state_filter)
)

Impact: API now correctly returns all fees when no filters are applied, and properly filters when they are.

Issue #4: Incorrect Sort Syntax

AI Generated:

sort = { "$db.fees.updated_at": "desc" }

The Problem: XanoScript doesn't use $db. prefix in sort blocks. Caused silent sorting failures.

My Fix:

sort = { fees.updated_at: "desc" }

Impact: Last updated fees now correctly sorted by timestamp.

What I Added Beyond AI

1. API Key Authentication System

function auth_api_key() {
  // Extract and validate API key
  var $api_key { value = get($http_query, "api_key") }

  if (!$api_key) {
    throw {
      code: "ERROR_CODE_ACCESS_DENIED",
      message: "Missing API Key"
    }
  }

  // Query and validate
  var $key_record { 
    value = db.get('api_keys', { 
      key: $api_key, 
      is_active: true 
    }) 
  }

  if (!$key_record) {
    throw {
      code: "ERROR_CODE_ACCESS_DENIED",
      message: "Invalid or inactive API Key"
    }
  }

  // Update usage stats
  db.update('api_keys', $key_record.id, {
    request_count: $key_record.request_count + 1,
    last_request_at: now()
  })

  return $key_record
}

2. Standardized Error Responses

{
  "code": "ERROR_CODE_ACCESS_DENIED",
  "message": "Invalid or inactive API Key.",
  "status": 401
}

3. Comprehensive Documentation

Full API reference with request/response examples
Quick Start guide (5 minutes to first API call)
Code examples in JavaScript, Python, and cURL
Data sources reference with official URLs

The Numbers: AI vs Human Contribution

Metric	AI	Human
Time	30 minutes	4-5 hours
Code Generated	~500 lines	~300 lines
Critical Bugs Found	0	5
Production Features	Basic CRUD	Auth, optimization, error handling
Documentation	None	Complete

Total Development Time: ~5 hours (would have been 10-12 hours without AI)

My Experience with Xano

What I Found Most Helpful

1. Visual Database Designer
Building the relational database schema with proper foreign keys was intuitive. The visual interface made it easy to see relationships between tables (fees → subcategories → categories → agencies).

2. Built-in API Testing
The "Run & Debug" feature in the API builder was invaluable. I could test endpoints immediately without deploying or using external tools. This caught bugs early.

3. XanoScript Flexibility
Having both visual blocks and code gave me the best of both worlds. For simple queries, I used the visual builder. For complex logic (like the authentication function), I wrote XanoScript directly.

4. One-Click Deployment
No server setup, no deployment configuration, no DevOps complexity. Just build and it's live. This saved hours of infrastructure work.

5. PostgreSQL Under the Hood
Knowing I had a real relational database with proper ACID guarantees gave me confidence. This isn't a toy database—it's production-grade.

Challenges I Faced

1. XanoScript Learning Curve
Coming from Java/JavaScript/Python, XanoScript syntax had quirks:

$variable vs variable naming conventions
When to use eval blocks (spoiler: less than I thought)
Sort/filter syntax differences from standard SQL

Solution: Trial and error, plus reading Xano docs. The AI-generated code gave me examples to learn from, even when it had bugs.

2. Debugging AI-Generated Code
AI confidently generated invalid syntax ($db.{}) that looked plausible. Without testing, I would have shipped broken code.

Lesson Learned: Always test AI-generated code immediately. AI is great at structure but can miss framework-specific nuances.

3. Documentation Gaps
Some XanoScript features weren't well-documented online. I had to experiment to figure out the correct syntax for complex joins and aggregations.

Solution: Used the Xano community forums and tested different approaches until I found what worked.

4. N+1 Query Gotcha
It was easy to accidentally create performance problems with nested loops. The visual builder doesn't warn you about N+1 queries.

Solution: Always think about database query patterns. Single complex query > multiple simple queries.

What Made This Project Successful

The Winning Combination:

✅ Xano handled infrastructure and deployment
✅ AI generated boilerplate and structure quickly
✅ Human expertise fixed bugs, optimized performance, added production features
✅ Real data from official government sources made it valuable

None of these alone would have worked. But together? I built a production-ready API in ~5 hours that would have taken 2-3 days manually.

Would I Use Xano Again?

Absolutely. For rapid API development, especially for:

Hackathons - Speed to deployment is unbeatable
MVPs - Get to market fast, validate ideas
Internal tools - Build CRUD APIs in hours, not days
Prototypes - Prove concepts before investing in custom infrastructure

When I might not use it:

Extremely high-scale applications requiring custom infrastructure
Projects needing specific database features outside PostgreSQL
Complex real-time features requiring WebSockets at scale

But for 90% of backend API projects? Xano + AI is a game-changer.

Impact & Future Plans

Who Can Use This API?

🏦 Fintech Companies:

Budget calculators including government fees
Payment platforms for government services
Financial planning apps

📱 Mobile Apps:

Citizen services super-apps
Student planning tools
Government service aggregators

🤖 Chatbots:

WhatsApp bots for fee inquiries
USSD services for feature phones
AI government assistants

What's Next

Immediate (v1.1):

Implement rate limiting (100 req/hour)
Add webhook support for fee updates
Create admin dashboard for data management

Future (v2.0):

Expand to all 36 Nigerian states
Historical fee tracking (price changes)
Multi-language support
Mobile SDK

Long-term Vision:
Transform into a comprehensive government services platform with payment processing, application tracking, and document verification.

Data Sources

All fees sourced from official government documents:

NIMC: SERVICE_LEVEL_AGREEMENT_2025_.pdf
NIS: Official Immigration Service SLA
NECO: Official exam fees from neco.gov.ng
JAMB: Payment services from jamb.gov.ng
NERC/EKEDC: Official tariff plans from ekedp.com

Every fee includes verification_url linking to the official source for transparency.

Try It Now!

Test API Key: nga_b6cf98a60bda43ba8cf54af9dbd87260

Quick Test:

curl 'https://xmlb-8xh6-ww1h.n7e.xano.io/api:public/fees/search?q=passport&api_key=nga_b6cf98a60bda43ba8cf54af9dbd87260'

Full Documentation: GitHub Repository (includes Quick Start guide, complete API reference, and code examples)

Conclusion

This project proves that AI-assisted development works best as a partnership: AI provides speed and structure, humans provide critical thinking and domain expertise.

The Nigerian Government Fees API solves a real problem affecting millions. By centralizing scattered information into one well-documented API, we're removing barriers to accessing essential government services.

More importantly, this is just the beginning. With a solid foundation, this can grow into a platform that truly improves how Nigerian citizens interact with public services.

Questions? Want to contribute? Drop a comment below! 🚀

DEV Community: AbdulmalikAlayande

Realtime from First Principles, Part 2: WebSocket and The WebSocket Protocol

The WebSocket Protocol

Realtime from First Principles, Part 1: How the Web Learned to Fake Realtime

The Origins of HTTP

The Rise of JavaScript

Early Attempts at Realtime

AJAX (Asynchronous JavaScript and XML)

Comet

The Cost of Hacking HTTP

Limited Scalability

Unreliable Message Ordering and Delivery Guarantee

No Bidirectional Streaming

Higher Latency

Building an RPC Server From Scratch in TypeScript

Table of Contents

Building an RPC Server From Scratch in TypeScript

Table of Contents

OAUTH2.0 In Action — A Guide To Implementing OAUTH In Apps and Websites.

Table of contents

What is OAUTH

How Does OAUTH Work

A trip to OAUTH1.0Ville

What is OAUTH2.0

Examples of OAUTH Technologies

OIDC (Open ID Connect)

Hands-on Implementation with Microsoft Entra ID

Step 1: Register your app in Microsoft Entra ID

Step 2: Get a secret (or better, a certificate)

Step 3: Add the permissions you need

Step 4: Send the user to log in (authorization request)

Nigerian Government Fees API: AI-Powered Public Service Data

What I Built

API Documentation

Core Resources

1. POST /api_key/generate

2. GET /fees

3. GET /fees/{id}

4. GET /fees/search

5. GET /categories

6. GET /metadata

Rate Limits

Response Format

Demo

Example 1: Generate API Key

Example 2: Get All Categories

Example 3: Search for NIN Fees

Example 4: Get Fee Details

Code Integration Examples

The AI Prompt I Used

How I Refined the AI-Generated Code

Issue #1: Invalid eval Syntax - CRITICAL BUG

Issue #2: N+1 Query Performance Problem

Issue #3: Empty Results Bug

Issue #4: Incorrect Sort Syntax

What I Added Beyond AI

The Numbers: AI vs Human Contribution

My Experience with Xano

What I Found Most Helpful

Challenges I Faced

What Made This Project Successful

Would I Use Xano Again?

Impact & Future Plans

Who Can Use This API?

What's Next

Data Sources

Try It Now!

Conclusion

Issue #1: Invalid `eval` Syntax - CRITICAL BUG