Having a powerful tool like this available offline is a game-changer. These Local LLMs keep high-level intelligence at your fingertips, even when you're offline. By the end of this guide, you’ll understand what local LLMs are, why they matter, and how to run them yourself, both the easy way and the more technical way.

This guide is suited but not limited to:

• Developers, technical writers, or curious engineers.

• Anyone comfortable with the terminal.

• People with some exposure to AI tools (ChatGPT, Claude, and so on).

• Anyone with little or no experience running LLMs locally.

Table of Contents

• What Are Local LLMs?

• What Running “Locally” Means

• Why Run LLMs Locally?

• How to Set Up a Local LLM

• What Is Ollama?

• How Ollama Operates

• How to Install Ollama

• How to Pull an LLM

• How to Run Your LLM

• How to Customize Local LLMs in Ollama with Modelfiles

  • What Are Modelfiles?

  • How to Customize a Model

  • What Modelfiles Do and Don't Do

• Conclusion

What are Local LLMs?

Local Large Language Models (LLMs) bring AI off the cloud and onto your personal hardware. While standard models are originally too large for consumer devices, a process called quantization reduces their numerical precision, much like compressing a large high-resolution video file so it can stream smoothly on a mobile phone. This allows powerful intelligence to run locally on your laptop without needing massive server farms.

Running models such as Meta’s Llama 3.3, Google’s Gemma 3, or Alibaba’s Qwen series locally ensures full data privacy and eliminates subscription costs. Because the AI lives on your machine, you get a fast, offline-capable workspace that keeps your code secure and under your direct control.

What Running “Locally” Means

To understand how local LLMs run on your machine, you have to look into the physical components of your computer. When you run a model like Llama 3 or Mistral locally, your hardware transforms from a general-purpose machine into a specialized AI engine.

The process relies on a tight coordination between four key hardware pillars: Storage, RAM, the GPU, and the CPU.

Storage (The model's permanent home)

Before you can chat, you must download the model. Unlike a standard app, an LLM is primarily a massive file of "weights", numerical values that represent everything the AI knows.

• The Files: You’ll likely see formats like .gguf or .safetensors. These files are large: a "small" 7B (7 billion parameter) model usually occupies 5GB to 10GB of disk space.

• SSD vs. HDD: An SSD is mandatory. Because the computer must move several gigabytes of data into memory every time you launch the model, a traditional hard drive will leave you waiting minutes for the "brain" to wake up.

VRAM and RAM (The Model’s Workspace)

This is the most critical bottleneck. For an AI to respond quickly, its entire "brain" must fit into high-speed memory.

• VRAM (Video RAM): This is the memory physically attached to your graphics card (GPU). It is significantly faster than regular system RAM. If your model fits entirely in VRAM, the AI will likely type faster than you can read.

• System RAM: If your model is too big for your GPU, the software will "spill over" into your computer’s regular RAM. While this allows you to run massive models on modest hardware, the speed penalty is severe—often dropping from 50 words per second to just one or two.

The GPU (The Mathematical Engine)

While your CPU is the "manager" of your computer, the GPU (Graphics Processing Unit) is the "mathematician."

• Parallel Power: LLMs work by performing billions of simple math problems (matrix multiplications) at the same time. A CPU has a few powerful cores, but a GPU has thousands of smaller cores designed specifically for this parallel math.

• Unified Memory (Apple Silicon): On modern Macs (M1/M2/M3), the CPU and GPU share the same pool of memory. This "Unified Memory" is a game-changer for local AI, allowing even thin laptops to handle relatively large models that would typically require a chunky desktop GPU.

For optimal performance, always compare your computer's specs with the model’s requirements to see which models you can comfortably run.

Why Run LLMs Locally?

Running an LLM locally isn't just for tech enthusiasts, it’s a strategic move for anyone who wants full control over their AI. Core benefits of running an LLM locally are:

1. Offline Usage: You're not limited to the cloud. You can explore and use your data wherever you go. Whether you're on a plane or in a remote area, your AI works without an internet connection.

2. Privacy and data ownership: Also, because you are not connected to the cloud, there is no risk of your data and prompts being exploited by a third party remotely or used to train a company’s next model.

3. Cost control: No need for monthly subscriptions and API tokens. Once you have the hardware, running the model is essentially free, given its capabilities and your configurations.

4. Customization & Experimentation: If you have multiple models downloaded, you can "swap brains" instantly. Try different models, fine-tune them for specific tasks, and tweak settings that big providers keep locked.

5. Faster iteration for dev workflows: For developers, local hosting eliminates network latency, allowing for near-instant responses and faster testing loops.

Tradeoffs

Local LLMs have certain tradeoffs to consider:

• Hardware Requirements: You’ll need a decent setup—specifically, a GPU with a good amount of VRAM (usually 8GB+) or a Mac with Apple Silicon (M1/M2/M3)—to achieve smooth performance.

• Performance Limitations: Local models are getting better every day, but they might not yet match the sheer "reasoning power" of a massive, billion-dollar cloud cluster like GPT-4.

• Initial Setup Friction: It isn’t always "plug and play." If you want to get hands-on with specific features, you will have to spend some time configuring software, downloading large model files, and troubleshooting your environment.

Even with these trade-offs, having such a tool at your disposal and under your control remains a significant advantage in everyday life.

How to Set Up a Local LLM

There are many ways to get and set up a local LLM, but for this guide, you will use Ollama, a user-friendly tool that brings private, secure AI directly to your desktop. You will learn to pull and deploy high-performance models with a single command, optimize them for your specific CPU/GPU configuration, and use the powerful Modelfile system to "program" custom AI personalities tailored to your exact needs.

What We’ll Cover:

• The Basics: Understanding how Ollama turns your PC into an AI powerhouse.

• Installation & Setup: Getting up and running in under five minutes.

• Model Management: How to find, "pull" (download), and run models like Llama 3 or Mistral.

• Customization: Writing your first Modelfile to give your AI a specific job or personality.

By the end of this, you will have a fully independent AI workstation, capable of sophisticated reasoning without ever sending a byte of data to the cloud.

What is Ollama?

Ollama is a free, open-source tool that makes running Large Language Models (LLMs) on your own hardware as easy as opening a web browser. It strips away the technical complexity that usually comes with AI research, giving you a clean, simple way to chat with, manage, and even customize your own AI models.

Before Ollama, running a local AI was a headache. You had to hunt for the right "weights" files on the internet, set up complex coding environments, and hope your hardware doesn't crash. Now, instead of spending hours configuring software, Ollama handles the heavy lifting. It automatically finds your graphics card (GPU) and tunes the settings for you.

How Ollama Operates

Ollama follows a simple "Mental Model" that mimics how you handle apps on a phone or music on a streaming service.

The Model Registry (The Library)

Ollama maintains a massive "Library", a central library of prepackaged AI models such as Llama 3, Mistral, and Gemma. You don't have to worry about file formats, you just pick a name from the list, and Ollama "pulls" it down to your machine.

The Local Runtime (The Engine)

Once you have a model, Ollama acts as the engine. It wakes the model up, loads it into your computer's memory (RAM/VRAM), and starts the mathematical "thinking" process. It is smart enough to use your GPU for speed, but it can also run on a standard CPU if that's all you have.

The CLI (The Control Centre)

Ollama uses a Command Line Interface (CLI). While that sounds technical, it just means you type simple, human-like instructions into a terminal window. Want to talk to a model? You just tell it to run. Want to see what you've downloaded? You ask it to list them.

How to Install Ollama

Go to the Ollama download page. For Windows and Mac, click the download button.

For Linux, run this command:

curl -fsSL https://ollama.com/install.sh | sh

After downloading, open the file, follow the setup instructions, and install it.

On Windows and Mac, after installation, the Ollama native Desktop Application should open.

This GUI is most beneficial for those who feel the CLI is intimidating; you don't have to be a coder to use Ollama. Instead of typing commands, you can manage your models and start conversations through a sleek window that feels just like any other chat app.

How to Pull an LLM

As mentioned earlier, Ollama has a vast library of Large Language Models for different specs and uses. To download one to your computer, use the pull command followed by the name of the LLM. For example:

ollama pull gemma3:1b

To see the models you downloaded or have, use the list command, like:

ollama list

How to Run Your LLM

You now have your LLM on your computer. To use it, you use the run command, followed by the name of the LLM. For example:

ollama run gemma3:1b

The LLM will load up, and you can prompt it.

To exit the LLM, use Ctrl + d or type in /bye.
You can perform other operations like deleting a model, copying a model, show information on a model, and so on. Type in ollama help to see all these commands.

How to Customize Local LLMs in Ollama with Modelfiles

One of Ollama’s most powerful features is the ability to customize how a local model behaves using Modelfiles. Rather than treating models as fixed black boxes, Modelfiles allow you to define how a model should respond, what role it should play, and how it should generate text, without retraining or fine-tuning.

This makes Modelfiles ideal for creating reusable, task-specific local models such as technical writers, code reviewers, research assistants, internal developer tools, or even character-driven assistants.

What are ModelFiles?

A Modelfile is a plain-text configuration file used by Ollama to create a new model based on an existing one. It describes how a base model should be wrapped, prompted, and configured at runtime.

Essentially, a Modelfile:

• Starts from a base model

• Applies a set of instructions

• Produces a new, named model that can be run like any other

Modelfiles do not modify the underlying model weights. Instead, they define behavioral rules, how the model should be prompted, how it should generate text, and how it should respond to user input.

Modelfile Syntax and Structure

Modelfiles are line-based and declarative. Each directive defines a specific aspect of the model’s behavior.

A minimal Modelfile looks like this:

FROM llama3

SYSTEM """
You are a senior technical writer.
"""

PARAMETER temperature 0.2

• FROM: This is the foundation. It tells the system which base architecture (like llama3) to inherit its intelligence and tokenizer from.

• SYSTEM: This sets the "permanent" instructions. By assigning the Senior Technical Writer role, we ensure that every response maintains a professional, structured tone without needing to remind the AI in every prompt.

• PARAMETER: These are the model's dials and knobs. In this case, we use the temperature 0.2 parameter to set a low "creativity dial," forcing the model to be more deterministic and precise, which is ideal for the consistent, factual output.

Advanced users can also use TEMPLATE for custom prompt formatting and additional MESSAGE directives to include specific conversation history, though these aren't required for this basic setup.

Quick reference cheat sheet:

How to Customize a Model

To create a model using a Modelfile, Ollama performs the following steps:

• Loads the specified base model

• Applies system-level instructions

• Configures generation parameters

• Registers the result as a new local model

For this article, you will be creating a technical writing assistant from any local LLM of your choice. You can use the LLM you downloaded earlier, or download another one you feel is a better fit for this model.

1. Set up your environment: Create a folder named my-writing-assistant, then open it in your preferred IDE or text editor.

2. Create a Modelfile: Create a file named Modelfile in your folder. Populate it with the following:

FROM llama3 

SYSTEM """
You are a senior technical writer.
Write clear, concise explanations.
Use headings and bullet points where appropriate.
Avoid marketing language.
"""

PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.1
PARAMETER num_ctx 4096

1. Create your model: Open the terminal in your IDE, or if you are using a text editor without a built-in terminal, open your Command Prompt and navigate into the my-writing-assistant directory. Run this command:

   ollama create tech-writer -f Modelfile
   

   You should see a response like this:

   

2. Run your model: You can run your model like any other Ollama model, with the run command:

   ollama run tech-writer
   

   

   Try a documentation-based prompt and see your model behave exactly how your Modelfile designed it.

You can also interact with your models(downloaded and modified) using the Desktop App. Simply open the application, select your preferred model from the chatbox dropdown menu, and start prompting.

What Modelfiles Do and Don't Do

Modelfiles are powerful, but it’s important to understand their scope.

They:

• Customize model behavior

• Enforce consistent prompting

• Tune generation characteristics

• Create reusable local models

They do not:

• Retrain or fine-tune model weights

• Add new knowledge

• Change the model’s architecture

A Modelfile shapes how a model responds, not what it knows.

Conclusion

Running large language models locally is no longer limited to researchers or high-end machines. With Ollama and Modelfiles, you can download capable models, run them on your own device, and tailor their behavior to fit your workflow.

In this guide, we covered what local LLMs are, why they matter, how Ollama simplifies setup, and how Modelfiles let you control tone, structure, and generation settings. Instead of relying on a generic chatbot, you can build assistants that feel intentional and purpose-built.

More importantly, running models locally changes how you interact with AI. You move from simply consuming an API to understanding and shaping the system itself. As AI continues to influence software, business, and everyday tools, hands-on experience with local models gives you a clearer view of where the technology is heading. The best way to understand that shift is to experiment, pull a model, refine a Modelfile,

This article will guide you through the basics of npm, explain how it functions behind the scenes, and demonstrate step-by-step how to create and publish your own npm package to the official npm registry. Whether you’re a beginner just starting with JavaScript or a seasoned developer who has used npm but never published a package, this guide will help you confidently navigate the entire process, from setup to sharing your code with the global developer community.

Table of Contents

• What is npm?

• Components of npm

• The Command Line Interface

• The Registry

• The Website

• What is the Package.json File?

• How npm Works

• How to Publish an npm Library

• How to Verify and Install Your Package

• How to Update Your Package

• Notes and Best Practices

• Beyond the Basics

• Conclusion

What is npm?

npm, which stands for Node Package Manager, is a command-line tool for installing and managing JavaScript packages. It is an ecosystem that powers modern JavaScript development (Node.js, frontend tools, frameworks, and so on). Developers use npm to share and borrow packages, and many organizations use npm to manage private development.

Essentially, npm is to JavaScript what pip is to Python or Maven to Java. It enables developers to reuse code written by others (most of the time to fulfil a function in their project), manage dependencies, and share their own code with the world.

You can use npm to:

• Get and utilize code packages in your applications, either as-is or with custom modifications.

• Download and run standalone tools instantly.

• Execute packages directly from the registry without installing them using npx.

• Share your own code with developers around the world through the npm registry.

• Limit access to specific packages so only approved developers can use them.

• Create organizations to manage code, teams, and packages in one place.

• Collaborate as virtual teams using shared organizational accounts.

• Handle different versions of packages and their dependencies with ease.

• Keep your applications up to date by syncing with the latest package updates.

• Explore different packages that offer various solutions to the same problem.

• Connect with developers working on similar challenges and projects.

Components of npm

npm consists of three core components:

• The command line interface (CLI)

• The registry

• The website

The Command Line Interface

There are different npm commands you can run on your terminal. For example, npm init can be used to initialize a Node project, npm install can be used to install a package. It also allows you to do things like:

• Publish packages (npm publish)

• Update packages (npm update)

• Manage versioning (npm version)

• Run scripts (npm run build, npm test, and so on)

Think of it as your control panel.

The Registry

You can find the huge public database at https://registry.npmjs.org, where packages are stored and shared. It also contains all the meta-information surrounding the package.

Example, when you run:

npm install express

npm fetches the Express package from the registry.

The npm registry enables collaboration by allowing developers to:

• Publish their own packages

• Install packages created by others

• Discover new tools and libraries

Its collaboration features include:

• Open-source packages: The code is publicly visible (usually hosted on GitHub).

• Versioning: Multiple versions of the same package let users safely adopt updates.

• Scoped packages: Namespaces allow teams and organizations to manage ownership.

• Issues & pull requests: Most npm packages link to GitHub, allowing developers too contribute fixes and enhancements.

• Organisations: Teams can manage access to shared private or public packages.

The Website

At https://www.npmjs.com, this is where you can:

• Browse packages.

• Read documentation.

• View download stats and dependencies.

• Create and manage your account, organization, and package access.

What is the Package.json File?

A very important component of any npm tool that you’ll come across as a JavaScript developer installing an npm package, is the package.json file. It is a metadata file that lives at the root of every npm or Node project. It tells npm (and other tools) everything it needs to know about your project, like:

• What the project is called.

• What it depends on

• How to run it

• How to version it

• and how to publish it

You can think of it like the blueprint of your JavaScript project. Without it, npm doesn't know how to work with your code.

You can create a package.json file by typing the command npm init in your terminal and filling in the prompts provided. Alternatively, you can create a file named package.json and manually populate it with JSON content.

Key Fields in an npm package.json File

The following is a list of commonly used fields and how they interact with npm:

1. name and version

    "name": "my-awesome-package",
    "version": "1.0.0"
   

   • This is required for publishing.

   • name must be unique (if publishing to the public npm registry).

   • version follows semantic versioning (semver) (for example, major.minor.patch).

2. description, keywords, author, and license

    "description": "A utility to convert markdown to HTML",
    "keywords": ["markdown", "html", "converter"],
    "author": "Ikegah Oliver",
    "license": "MIT"
   

   • Helps npm users discover your package

   • Show up on npmjs.com.

   • Sets collaboratory license

3. scripts

    "scripts": {
      "start": "node index.js",
      "test": "jest",
      "build": "tsc"
    }
   

   • Defines custom commands.

   • Run with npm run test, npm run build, and so on.

   • Automates build, test, lint, deploy processes.

4. main and exports

    "main": "dist/index.js",
    "exports": {
      ".": "./dist/index.js"
    }
   

   • main: Entry point for require() or import.

   • exports: Controls exactly what parts of your package are exposed (especially useful for modern ESM and package security).

5. dependencies and devDependencies

    "dependencies": {
      "express": "^4.18.2"
    },
    "devDependencies": {
      "eslint": "^8.0.0",
      "jest": "^29.0.0"
    }
   

   • dependencies : Core packages your project needs to run in production (for example, express).

   • devDependencies : Packages used only during development, like testing or build tools (for example, jest).

6. engines

    "engines": {
      "node": ">=14.0.0"
    }
   

   • Specifies Node.js version your package supports.

   • Helps warn users before they install with an unsupported version.

7. private

    "private":"true"
   

   • Prevents accidental publishing to the public npm registry.

   • Used for monorepos and internal-only projects.

8. files (optional)

    "files":["/dist", "README.md"]
   

   • Controls what files get included when you run npm publish.

   • Reduces package size, omits build artifacts or test files.

A minimal npm package.json file looks like this:

{
  "name": "@oliver/markdown-to-html",
  "version": "1.0.0",
  "description": "Converts markdown to HTML with styles",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "test": "jest"
  },
  "keywords": ["markdown", "html", "converter"],
  "author": "Ikegah Oliver",
  "license": "MIT",
  "dependencies": {
    "marked": "^5.0.0"
  },
  "devDependencies": {
    "jest": "^29.0.0"
  },
  "engines": {
    "node": ">=14.0.0"
  },
  "files": ["dist/", "README.md"]
}

The package.json file plays a central role in every npm workflow. It defines your project's identity, lists its dependencies, specifies useful scripts, and outlines how the package should behave when published. Without it, npm can't properly install packages, run commands, or publish your code to the registry.

How npm Works

When you type npm install in your terminal, npm initiates a behind-the-scenes process to install the necessary packages for your project. Depending on how you run the command, the process varies slightly as follows:

Method 1 - package.json Already Has Dependencies

If your package.json lists packages under dependencies or devDependencies, npm will:

1. Read those entries: It looks at the names and version ranges of each dependency.

2. Contact the registry: npm queries https://registry.npmjs.org to fetch metadata about each required package.

3. Download the correct versions: It selects versions that match your version rules (such as ^4.17.0) and downloads the .tgz files.

4. Unpack and install: It places the packages into the node_modules directory and caches them.

5. Update package-lock.json: It logs the exact versions and dependency tree in this file to ensure consistent installs later.

Method 2 - You Run npm install <package-name> Without Existing Dependencies

If your package.json doesn't have any dependencies yet and you run something like this in your terminal:

npm install express

Then npm will run:

1. Resolve the package version: It fetches the latest version of Express (unless you specify a version manually).

2. Download and install: The tarball is downloaded and placed in the node_modules/ folder that is automatically generated. A tarball is the zipped-up version of the package (express in this case), containing the package’s JavaScript files, a package.json, a README, and anything else the author included for distribution that npm downloads and extracts onto your machine.

3. Add to package.json: npm automatically adds the package to your dependencies list like this:

"dependencies": {
  "express": "^4.18.2"
}

4. Create a package-lock.json (if it doesn't exist): It writes all the version info to lock things down for future installs.

Note: If you run npm install --save-dev jestIt’ll add the package under devDependencies instead.

How to Publish an npm Library

To follow through with this guide section, you will need to have the following prerequisites:

• Stable network connection

• A code editor with a terminal (like VSCode)

• Basic knowledge of JavaScript and Node

• A basic understanding of the Markdown Markup language (for README documentation)

Now, let’s dive into publishing an npm library. Assuming you just built and tested a fantastic JavaScript tool that you would like to share with the world, and allow people to use it in their projects and applications, the steps below will guide you from having the tool on your local machine to making it publicly available as an npm package for anyone to install and enjoy:

Step 1: Create a free npm account

Before publishing, you will need an npm account.

• Go to https://www.npmjs.com/signup.

• Fill in the form with your username, email, and password.

• Confirm your email address by clicking the link in the verification email.

Step 2: Log in from the Command Line

Once you’ve created your account, you need to log in through your terminal. Run:

npm login

npm will prompt you for your username, password, and email address. If everything is correct, npm will generate an authentication token and store it locally, so you don’t have to log in every time.

Step 3: Create a package.json file

If your project doesn't already have a package.json file, create one by typing this command in your terminal:

npm init

You will be prompted to fill in the following information:

• name: Must be unique if it’s public.

• version: Start with 1.0.0 (it represents the first version of your project; subsequently, you will change it accordingly after each update push)

• description: One-line summary of your package.

• entry point: Entry file of your project, usually index.js or dist/index.js.

• keywords: Help others discover your package.

• author: Your name or GitHub handle.

• license: Use MIT, ISC, or another open-source license.

When you’re done, npm will generate a package.json like this:

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "description": "A demo package for npm publishing",
  "main": "index.js",
  "keywords": ["demo", "npm", "tutorial"],
  "author": "Your Name",
  "license": "MIT"
}

Step 4: Add a README.md

Explain what your package does and how to use it in a README.md file. The README appears on your package page on npmjs.com. Example content:

# my-awesome-package

A simple package that says hello.

## Usage

```js
const greet = require('my-awesome-package');
console.log(greet('Oliver'));
// Output: Hello, Oliver!

Step 5:Add an .npmignore file

This will exclude folders like node_modules, dist, or .env, and any other file or folder within the package you don’t wish to publish. Example content:

node_modules
.env
dist

Step 6: Check if the package name you chose is available

Before publishing, check if the package name you chose is not already taken. To check, run this command on your terminal:

npm search my-awesome-package

Or enter the URL https://www.npmjs.com/package/my-awesome-package in your browser (replace my-awesome-package with the name you chose). If no package page shows up, the name is not taken.

If the package name has been taken, change it in your package.json and any documentation (README.md), the name is reflected, or publish it under a scope. A scope is like a namespace tied to your npm username or organization. It ensures your package name is unique, even if the base name is common. For example, if my-awesome-package is taken, you can publish under a scope by setting the name section in its package.json like this:

{
  "name": "@yourname/my-awesome-package"
}

Step 6: Publish your package

You are now ready to publish. Run:

npm publish

If you used a scoped name, when publishing, you must make it public:

npm publish --access public

If everything is valid, npm will publish your package and give you a URL like:

https://www.npmjs.com/package/my-awesome-package

How to Verify and Install Your Package

Visit your project page on npm to see it live. For example: https://www.npmjs.com/package/my-awesome-package, or search your project name on the npm website search bar.

Now, try installing it in a node project:

npm install my-awesome-package

Test out its features and functionalities, depending on what it is built to do.

How to Update Your Package

If you make changes or update features in your package, you can publish the update.

After applying your changes, you can update the version in your package.json. Using semantic versioning, you can update it as follows:

• Patch update: 1.0.0 → 1.0.1

• Minor update: 1.0.0 → 1.1.0

• Major update: 1.0.0 → 2.0.0

Or you can use the CLI:

npm version <update_type>

Replace <update_type> with your new semantic version.

Now run:

npm publish

Notes and Best Practices

Although publishing to npm is straightforward, you still need to follow best practices to maintain a clean, secure, and user-friendly package.

• Exclude Sensitive Files: Never include .env, credentials, or secrets. Use .npmignore or the "files" field in package.json to control what gets published.

• Test Before Publishing: Run npm pack to preview the package and install it locally in another project to ensure everything works.

• Unpublish Carefully: You can unpublish within 72 hours using npm unpublish --force, but avoid doing this frequently to prevent breaking other projects that rely on your package.

• Always Bump the Version: npm won’t let you overwrite a version, so use semantic versioning (npm version patch|minor|major) before publishing updates.

• Add Essentials: Include a clear README.md file, a license, and relevant keywords to make your package discoverable and easy to use.

Beyond the Basics

Now that you've got the hang of the basics, you can put your npm skills to work and level up as a developer. Here are some simple, practical steps you can take:

Get Involved in Open Source

One of the best ways to gain real-world experience is by contributing to existing projects on npm. Check out their repositories on GitHub and GitLab and see how you can contribute to them. This teaches you how to collaborate, handle code reviews, and manage versions. A great way to start is by looking for projects on GitHub with a "good first issue" label.

Maintain Your Own Package

Publishing is just the first step. To truly master the process, keep your package up to date. This involves fixing bugs, listening to user feedback, and adding new features. You will quickly learn about versioning, ensuring your package remains compatible with older projects, and effectively manage dependencies.

Dig into Advanced Features

Explore advanced npm topics like semantic versioning, using private packages, creating scoped packages, and automating your releases with CI/CD pipelines. These are essential skills for any professional developer.

Taking these steps will help you transition from merely understanding npm to confidently utilizing it in real-world scenarios.

Conclusion

Congratulations! You have now learned the essentials of npm from the package.json file to publishing and maintaining a JavaScript package with the npm library. With this knowledge, you can share your JavaScript tools with the world, collaborate with other developers, and contribute to the growing ecosystem of open-source libraries.

By following best practices, testing locally, and learning from standard errors, you can confidently create packages that are clean, secure, and useful for other developers. Whether you’re building a small utility or a full-fledged framework, publishing on npm gives your ideas visibility and helps you contribute to the wider JavaScript community.

If you’d like to get hands-on experience collaborating on a real package, I published an npm project called route-pilot, a powerful CLI tool for testing and analyzing Express.js routes in your Node.js applications. I’m actively seeking contributors who want to enhance the code, add new features, or refine the documentation. It’s a simple way to practice working with npm in a collaborative setting while learning more about open-source development. Head over to the GitHub repo and join in. We’d love to have you on board!

REST works so well because it speaks the web’s native language. It uses familiar HTTP methods like GET, POST, PUT, and DELETE, treats data as resources, and follows clear conventions. All this makes it easy to understand, quick to implement, and widely supported, which is why most modern web APIs follow REST principles.

In this article, I will explore REST concepts and core principles while we build a simple Express application step by step. You will learn:

• What is REST architecture, and what are its advantages in web development?

• The core REST principles (statelessness, resources, HTTP methods, and so on)

• How to implement these principles in a real Express.js app

• Best practices for designing clean and consistent APIs

Here’s what we will cover:

• What is REST

• Why use REST?

• Core Principles of REST Architecture

• Build a Simple Express App

  • What is Express?

  • Set Up the Express App

  • Build RESTful Resources

  • Middlewares

  • Test your Express App

• Bad REST Practices to Avoid

• Conclusion

What is REST?

Representational State Transfer (REST) is a style of designing networked applications that emphasises a stateless client-server communication model centred around resources. Think of it like ordering at a restaurant: each time you ask for something, you have to tell the waiter exactly what you want, and they don't remember your previous orders.

RESTful APIs treat data as resources, each accessible through a unique web address (URI). Then, it leverages the standard actions defined by HTTP methods – POST to create new resources, GET to retrieve them, PUT to modify existing ones, and DELETE to remove them – providing a consistent and well-understood way to interact with data over the internet.

Why Use REST?

REST architectural principles offer a compelling set of advantages that contribute to building robust, scalable, and maintainable web services. Below are some of the key benefits that make REST a preferred choice for modern web development:

• Simplicity and familiarity: REST leverages standard HTTP, which is already well-understood by developers and infrastructure.

• Scalability: The stateless nature of REST allows for easy scaling of both client and server components independently.

• Flexibility and interoperability: RESTful APIs can be consumed by a wide variety of clients, regardless of the technology stack.

• Cacheability: REST's design supports caching mechanisms, leading to improved performance and reduced server load.

• Loose coupling: The client and server are independent, allowing for changes on either side without necessarily affecting the other.

• Visibility and monitoring: The straightforward nature of HTTP requests and responses makes it easier to monitor and debug interactions.

Core Principles of REST Architecture

REST (Representational State Transfer) is built on a few simple principles that make APIs easy to understand and use. Here’s a quick breakdown of the key ones:

Statelesness

Every request from the client to the server must contain all the information needed to process it. The server doesn’t store anything about the client between requests – no session, no memory of previous actions.

Example: If a user sends GET /movies/1, the server returns the movie data without needing to know whether the user is logged in or what they requested before.

This makes APIs easier to scale, since each request can be handled independently.

Resource and URIs

In REST, everything you work with is considered a resource – users, products, and so on. Each resource should be accessible via a unique, meaningful URL.

Example:

• /movies – a collection of movie resources

• /movies/42 – a specific movie with ID 42

Resources are treated like nouns. Actions are determined by the HTTP method used.

Standard HTTP Methods

REST takes full advantage of HTTP methods to describe what action you’re taking on a resource:

• GET – retrieve data

• POST – create a new resource

• PUT – update or replace a resource

• PATCH – partially update a resource

• DELETE – remove a resource

Example: To delete a movie, you’d send a DELETE request to /movies/42. That’s clear, consistent, and intuitive.

Uniform Interface

REST enforces a consistent structure for communication between client and server. This means all REST APIs should behave similarly, no matter who built them. It includes:

• Using URIs to identify resources

• Using standard HTTP methods

• Representing data in formats like JSON or XML

• Self-descriptive messages (for example, proper status codes and headers)

This consistency makes it easier for developers to understand and integrate with RESTful APIs.

Cacheability

Servers should label responses as cacheable (stored to be retrieved later) or not, so clients can reuse responses when appropriate. This reduces unnecessary server load and improves performance.

Example: A GET /movies response can be cached for 5 minutes if the data doesn’t change frequently. That means fewer repeated calls for the same info.

Client-Server Separation

The client (frontend) and server (backend) operate independently. The client just needs to know how to communicate with the API – it doesn’t care how the server handles data, and vice versa.

This separation allows teams to develop and scale frontend and backend systems separately.

The principles above help create APIs that are scalable, predictable, and easy to work with.

How to Build a Simple Express App

What is Express?

Express.js is a lightweight and flexible Node.js web application framework. Built on top of Node.js, it provides a robust set of features for building single-page, multi-page, and hybrid web applications and APIs. Think of it as a helpful toolkit that streamlines the process of setting up and managing web servers and routing requests.

In this exercise, you will be building an Express app that will:

1. Handle a simple in-memory collection of movies as a RESTful resource

2. Support basic CRUD operations using the appropriate HTTP methods (GET, POST, PUT, DELETE)

3. Parse incoming JSON requests using built-in middleware

4. Use a custom middleware function to validate movie input before creating or updating entries

5. Send clear and meaningful responses based on the outcome of each request

By the end, you’ll have a working API that follows REST principles and can be tested using a tool like Thunder Client or Postman.

Set Up the Express App

To get the most out of this exercise, there are a few tools and concepts you should already be familiar with. Since we’re focusing on REST principles and how to apply them using Express, we won’t dive deep into the basics of these prerequisites. Make sure you’re comfortable with the following:

• Node.js

• Npm

• Thunderclient extension

• Basic JavaScript

With that, let’s get started.

Open your command prompt and create a new directory (folder):

mkdir express-app

Navigate into your new directory:

cd express-app

Initialize an npm project:

npm init -y

Install the Express package in your project:

npm install express

Now, open your directory in your code editor with the following command:

code .

Create a new file, server.js, and set up your Express app in that file:

const express = require('express');
const app = express();
app.use(express.json());

app.listen(8000, () => console.log('Server running on port 8000'));

This snippet above sets up a basic Express server. It starts by importing the Express library you installed, enables JSON parsing for incoming requests (so we can work with request bodies), and listens on port 3000. It’s ready to handle RESTful routes like GET, POST, PUT, and DELETE as we build out our API.

To start your server, go back to your command prompt and type in this command:

node server.js

You should see this logged in your command prompt:

Build RESTful Resources

With our Express app set up, let’s build out the /movies resource using RESTful routes. We'll treat each movie as a resource and use HTTP methods to define what we want to do – retrieve, add, update, or delete movies. For simplicity, we'll store the movies in an in-memory array.

Here is the full set of routes. Add it in your server.js file just under your app.use(express.json()); line:

// In-memory database (for demonstration purposes)
// In a real application, you would use a database like MongoDB or PostgreSQL
const movies = [];

// Get all movies
app.get('/movies', (req, res) => {
  res.json(movies);
  console.log(movies);
});

// Get a particular movie by ID
app.get('/movies/:id', (req, res) => {
  const movie = movies.find(m => m.id === parseInt(req.params.id));
  if (!movie) return res.status(404).send('Movie not found');
  res.json(movie);
});

// Add a new movie
app.post('/movies', (req, res) => {
  const movie = {
    id: movies.length + 1,
    title: req.body.title,
    genre: req.body.genre,
    year: req.body.year
  };
  movies.push(movie);
  res.status(201).json(movie);
});

// Update a movie
app.put('/movies/:id', (req, res) => {
  const movie = movies.find(m => m.id === parseInt(req.params.id));
  if (!movie) return res.status(404).send('Movie not found');

  movie.title = req.body.title;
  movie.genre = req.body.genre;
  movie.year = req.body.year;

  res.json(movie);
});

// Delete a movie
app.delete('/movies/:id', (req, res) => {
  const movieIndex = movies.findIndex(m => m.id === parseInt(req.params.id));
  if (movieIndex === -1) return res.status(404).send('Movie not found');

  const deletedMovie = movies.splice(movieIndex, 1);
  res.json(deletedMovie);
});

The code above defines a complete set of RESTful routes for managing a movies resource using Express.

It begins with an in-memory array, movies, which acts as our temporary data store. The GET /movies route returns all books, while GET /movies/:id looks up a book by its ID using Array.find(), returning a 404 status if it's not found. The POST /movies route accepts JSON input, creates a new book with an auto-incremented ID, and adds it to the array, returning the new resource with a 201 Created status.

The PUT /movies/:id route handles full updates. It first finds the book, and if found, updates its title , genre, and year with the new values from the request body. The DELETE /movies/:id route removes a movie by finding its index in the array and using splice(). If the movie doesn't exist, both PUT and DELETE return a 404 error.

These routes demonstrate idempotency – that is, sending the same PUT or DELETE request multiple times will have the same effect as sending it once, a key REST principle. Each route also returns appropriate HTTP status codes and JSON responses, following REST conventions closely.

Each route follows a REST principle:

• Uses nouns for endpoints (/movies)

• Uses standard HTTP methods to express actions

• Ensure idempotency where appropriate (PUT, DELETE)

• Return appropriate status codes and messages

This structure keeps your API predictable and easy to use – exactly what REST is all about.

Middlewares

In RESTful APIs built with frameworks like Express, middleware plays a key role in maintaining clean, modular, and consistent request handling.

Middlewares are functions that sit in the middle of the request-response cycle in an Express app. When a client sends a request, middleware functions have access to the req (request), res (response), and next objects. They can inspect, modify, or act on the request before it reaches the route handler or even terminate the response early.

You have already seen a middleware here: app.use(express.json());. This is a global middleware that is used for parsing JSON. We will be creating a custom middleware for validating input for our POST and PUT requests.

Add the following code in your server.js file just before your routes:

// Middleware for simple validation
const validateMovie = (req, res, next) => {
  if (!req.body.title || !req.body.genre || !req.body.year) {
      return res.status(400).send('Title, genre, and year are required');
  }
  next();
};

This middleware function, validateMovie, performs basic validation on incoming requests before they reach the route handler. It checks if the title, genre, and year fields are present in the request body. If any of these fields are missing, it immediately responds with a 400 Bad Request status and an error message. If all required fields are provided, it calls next() to pass control to the next middleware or route. This keeps validation logic separate and reusable, helping maintain clean and RESTful route handlers.

To use this middleware, pass it as an argument in your POST and PUT routes, for example example:

app.post('/movies', validateMovie, (req, res) => {
  const movie = {
    id: movies.length + 1,
    title: req.body.title,
    genre: req.body.genre,
    year: req.body.year
  };
  movies.push(movie);
  res.status(201).json(movie);
});

Test Your Express App

To test the changes you have made, you need to restart your server. Go to your command prompt and press CTRL + C (for Windows) or Command + . (for MacOS). Input the start command like before to start the server again.

For this exercise, you will be testing the endpoints with the Thunder Client extension on VSCode. Thunder Client is a lightweight REST API extension for VSCode. With Thunder Client, you can your REST API routes and endpoints directly in VSCode.

To download Thunder Client, click on the Extension icon on the taskbar on your left and search “Thunder Client”. Then click Install:

After installation, you'll see the Thunder Client icon appear in your sidebar below the Extensions icon. Click it, then hit New Request to open a new tab. The request tab will open with a clean layout, ready for you to send and test API calls:

To start testing your API, set the request method (GET, POST, PUT, or DELETE) from the dropdown and enter the appropriate route, like http://localhost:3000/movies. For GET requests, just hit Send and you should see a response, in this case, an empty array []. To get a specific movie, you include an ID (for example, /movies/1).

For POST, PUT, and DELETE requests, switch to the Body tab and select the JSON format. Then provide the data you want to send:

• POST /movies: Add a new movie with {"title": "Movie Title", "genre": "Genre Name", "year": 0000}.

• PUT /movies/1: Update an existing movie with the same JSON structure.

• DELETE /movies/1: Remove a movie by its ID — no body is needed.

After sending each request, Thunder Client will display the response body, headers, and status code. Example:

Bad REST Practices to Avoid

When building REST APIs, aside from using the right HTTP methods, you also have to consider avoiding practices that break the core principles of REST. These bad practices can make your API harder to use, less predictable, or even misleading.

Here are some common REST bad practices and how to avoid them:

Using verbs in endpoints

Avoid routes like /getMovies or /createMovie. RESTful APIs rely on HTTP methods to express actions, so use nouns for endpoints and let methods do the talking — for example, use GET /movies to retrieve movies and POST /movie to create one.

Ignoring HTTP status codes

Returning 200 OK for every response, even errors, breaks REST conventions. Use the appropriate status codes: 201 Created for successful POSTs, 404 Not Found when a resource doesn’t exist, and 400 Bad Request for validation issues. This helps clients interpret responses correctly.

Overloading a single endpoint

Avoid writing one endpoint that changes behaviour based on the request body or headers. Each route should clearly map to a resource and method, like GET /movies/1 to fetch, and DELETE /movies/1 to remove, making the API predictable and easy to follow.

Not being idempotent where expected

PUT and DELETE should be idempotent, meaning repeated requests should have the same effect. If calling DELETE /movies/1 twice causes an error or unexpected behaviour, that’s a red flag. Design your handlers to handle these cases gracefully.

Exposing internal logic or database structure

Don’t leak internal details like database table names or query logic in your route naming (/api/movie_table_data). Keep your URIs clean, abstracted, and centred around the actual resource, like /movies.

Avoiding these practices not only keeps your API RESTful but also improves developer experience, consistency, and long-term maintainability.

Conclusion

You have explored the core ideas behind REST and put them into practice by building and testing a real Express API. This hands-on approach should help bridge the gap between theory and real-world application.

Along the way, you learned how REST treats resources, how to write clean and predictable routes, and why these principles matter when designing APIs that are easy to use and maintain.

Here’s a quick recap of what you’ve built and learned:

• Defined what REST is and why it’s widely used in web development

• Explored core REST principles like statelessness, resource-based routing, HTTP methods, status codes, and idempotency

• Set up a simple Express server to serve as the base for a RESTful API

• Built a complete set of routes (GET, POST, PUT, DELETE) for managing a movies resource

• Used middleware for tasks like JSON parsing and input validation

• Tested routes using Thunder Client and learned how to interact with each HTTP method

• Identified common REST anti-patterns and how to avoid them for cleaner design

To take your API further and follow more advanced RESTful practices, consider:

• Organising routes with Express Router to keep your code modular

• Adding robust error handling to return consistent and informative responses

• Using logging tools like morgan to monitor requests and debug more easily

• Securing endpoints with authentication methods like JWT or API keys

• Structuring responses consistently, possibly with pagination and filtering for larger datasets

• Validating user input thoroughly with libraries like Joi or express-validator

Explore the full project on GitHub, review the code, and try extending it with your features. Happy coding!

The answer is: they use APIs. These are powerful tools that drive mobile and web development and a wide range of applications, including cloud services, IoT devices, desktop software, and more.

APIs enable communication between applications, facilitating data exchange and verification.

In this article, you’ll learn all about APIs: the different types, their architecture, and the tradeoffs between the different architectures.

Here’s what we’ll cover:

• What is an API?

  • How Do APIs Work?

  • Why Are APIs Important?

• Types of APIs

  • Open APIs

  • Partner APIs

  • Internal APIs

  • Composite APIs

• Types of API Architecture

  • REST APIs

  • SOAP APIs

  • GraphQL APIs

  • gRPC APIs

• How to Choose an API Architecture

• Conclusion and Future Trends

This article is well-suited for beginners in web and mobile development and developers seeking a concise understanding of APIs and how they function.

What is an API?

API stands for Application Programming Interface. It is a set of rules and protocols that lets different software systems communicate with each other. An API defines how applications request services and exchange data, acting as a clear contract between a client and a server.

APIs simplify complex code into simple commands, letting developers connect systems and use built-in features without needing to know all the internal workings.

How Do APIs Work?

Imagine a restaurant: the customer (client) orders food through the waiter (API), who then communicates the order to the kitchen (server). The kitchen prepares the meal and sends it back through the waiter to the customer. Just like the waiter, the API handles requests and responses, letting the customer enjoy the meal without needing to know the details of the kitchen's operations.

A more practical example is when you buy a subscription online, and your payment information is securely sent to Paystack through its payment API. The API is a middleman that takes your request, verifies and processes your payment details with the bank, and then returns a confirmation to the website without directly exposing sensitive data.

Technically, a client initiates a request aimed at a server, specifying either data retrieval or procedural execution. Upon receiving and authenticating this request, the API performs the required operations. Then the API sends a response to the client, including the request's outcome (success or failure) and any requested data elements.

Why Are APIs Important?

APIs are crucial in software development because they make connecting different applications and services easier. They let you integrate external functionalities without building everything from scratch, saving time and reducing complexity through standardised commands.

For users, APIs also enhance security and user experience. They serve as secure gateways that filter data exchange between apps and external services, protecting sensitive information while ensuring smooth, reliable interactions.

Types of APIs

API types are mainly categorised by their accessibility and usage. There are four types of APIs, namely:

1. Open (Public) APIs

2. Partner APIs

3. Internal (Private) APIs

4. Composite APIs

Open APIs

Open APIs are APIs made available to the general public. This encourages developers, organisations, and other people to use them to develop applications, integrate them into their services, and improve them. Open APIs provide standardised access to data or services over the Internet.

Some very useful Open APIs include:

• TradeWatch – Real-time financial market data

• SerpAPI’s Search API – Real-time Google SERP API

• TwitterApi.io – Access real-time and historical data

• Instagram Post Generator – Generate posts with templates from popular IG pages

Partner APIs

Partner APIs are shared with specific business partners and often require authentication and agreements. They perform essential functions for businesses and applications.

For example, a payment API like Paystack directly communicates with service providers and banking platforms to process payments for products and services.

Internal APIs

Internal APIs are used for internal communication within an organisation. They enable integration and streamline internal processes. Internal teams use the API to access and share data between their applications. The API is not exposed to the public, ensuring that sensitive business logic remains secure.

An example is a company’s internal API that connects its HR, payroll, and project management systems.

Composite APIs

Composite APIs combine multiple API calls into a single request. They are instrumental in microservices architectures, where a single operation may require data from several services. A single API call triggers requests to multiple underlying APIs, and the composite API then combines the responses and returns a unified result.

For example, an e-commerce platform might use a composite API to fetch product details, pricing, and inventory information in one go, reducing latency and simplifying the integration process.

Types of API Architecture

APIs are structured differently depending on use case, scalability, security, and accessibility. There are multiple ways to structure an API, but we will only focus on the most prevalent architectural styles used in Web development. They include:

1. REST

2. SOAP

3. GraphQL

4. gRPC

REST APIs

Representational State Transfer (REST) is an architectural style that uses HTTP methods (POST, GET, PUT, DELETE) to perform CRUD (Create, Read, Update, Delete) operations on resource-based URIs.

REST APIs are built with frameworks like Express.js (Node.js), Django/Flask (Python), and Spring Boot (Java).

Key Components

1. Resources and endpoints:

   • The entities exposed by the API can include anything: users, products, documents, and so on.

   • Each resource is identified by a unique URI (Uniform Resource Identifier).

2. HTTP methods:

   • GET: Retrieves a resource.

   • POST: Creates a new resource.

   • PUT: Updates an existing resource.

   • DELETE: Removes a resource.

   • PATCH: Partially updates an existing resource.

3. Data representation:

   • Resources can have multiple representations (for example, JSON, XML).

   • The API responds with the requested representation, allowing data to be structured and parsed easily.

4. HTTP headers and query parameters:

   • HTTP headers provide additional information about the request or response.

   • They can be used for authentication, content negotiation, and other purposes.

5. Statelessness:

   • Each request from a client to a server must contain all the information needed to understand and process the request.

   • The server does not store any client state between requests.

Other notable components are cacheability, HTTP Status, and HATEOAS. Together, these components define the structure and behaviour of RESTful systems, enabling seamless and efficient communication between clients and servers.

Operation Overview

REST APIs expose resources through unique URIs and let clients perform operations using HTTP methods such as GET, POST, PUT, DELETE, and PATCH. Clients can request data in various formats, such as JSON or XML, and include additional details through HTTP headers and query parameters.

Each request is stateless and contains all the information required for processing without relying on stored client data. The API also uses HTTP status codes, cacheability, and HATEOAS to manage responses and guide further interactions, ensuring a seamless and efficient communication framework between clients and servers.

Practical Example and Real-world Use Cases

To illustrate how REST APIs work in practice, let’s consider a Book API that lets users manage a collection of books. Our example API has been created using the NodeJS and ExpressJS frameworks. I won’t explain how these frameworks actually work here, as that’s beyond the scope of this article. So if you don’t understand the syntax in the code below, don’t worry – just focus on the Requests and Responses logic.

This API follows REST principles by using standard HTTP methods to perform CRUD (Create, Read, Update, Delete) operations:

const express = require("express"); const bodyParser = require("body-parser");
const app = express(); app.use(bodyParser.json());

const app = express();
app.use(bodyParser.json());

// Dummy Database
let books = [
  { id: 1, title: "The Pragmatic Programmer", author: "Andy Hunt" },
  { id: 2, title: "Clean Code", author: "Robert C. Martin" },
];

// GET all books (Client requests, Server responds)
app.get("/books", (req, res) => res.json(books));

// GET a single book by ID
app.get("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  book ? res.json(book) : res.status(404).json({ message: "Not found" });
});

// POST a new book (Client sends data, Server updates database)
app.post("/books", (req, res) => {
  const newBook = { id: books.length + 1, ...req.body };
  books.push(newBook);
  res.status(201).json(newBook);
});

// PUT (Update) a book
app.put("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  if (book) {
    Object.assign(book, req.body);
    res.json(book);
  } else {
    res.status(404).json({ message: "Not found" });
  }
});

// DELETE a book
app.delete("/books/:id", (req, res) => {
  const index = books.findIndex((b) => b.id === parseInt(req.params.id));
  if (index !== -1) {
    books.splice(index, 1);
    res.json({ message: "Deleted" });
  } else {
    res.status(404).json({ message: "Not found" });
  }
});

app.listen(3000, () => console.log("API running on port 3000"));

Here’s what’s going on in this code:

• Client sends a request: A user (or frontend app) requests data using HTTP methods like GET, POST, PUT, or DELETE. Example: GET /books requests all books or POST /books posts a new book to the database.

• Server processes the request: The server receives the request, looks up the data (for example, from a database or in-memory array), and processes it.

• Server sends a response: The server sends back a JSON response containing the requested data or a confirmation message. Here’s an example:

[
  { "id": 1, "title": "The Pragmatic Programmer", "author": "Andy Hunt" },
  { "id": 2, "title": "Clean Code", "author": "Robert C. Martin" }
]

• Client receives and uses the data: The frontend or another service consumes the API response and displays or processes it accordingly.

Teams utilize REST APIs for web services, mobile apps, and cloud integrations. Social media platforms fetch posts, while e-commerce sites retrieve product details. Payment gateways process transactions and weather apps access real-time forecasts. REST’s simplicity and scalability make it the preferred choice for public and internal APIs.

SOAP APIs

The Simple Object Access Protocol (SOAP) uses XML for messaging and includes built-in standards for security, transactions, and error handling. Its formal contract is defined by a WSDL (Web Services Description Language).

This architecture prioritises security and reliability through features like WS-Security and transaction management, making it suitable for complex enterprise applications that require rigid standards and robust error handling.

SOAP APIs are created using frameworks or tools such as Apache CXF, .NET WCF, and JAX-WS (Java).

Key Components

1. SOAP envelope:

   • This is the root element of a SOAP message and defines the overall structure of the XML document.

   • It contains the SOAP Header and SOAP Body.

2. SOAP body:

   • This section contains the actual data being exchanged between the client and server.

   • It includes the request or response messages, which are typically structured as XML elements.

3. WSDL (Web Services Description Language):

   • This is an XML document that describes the web service, including its operations, message formats, and data types.

   • It acts as a contract between the client and server, outlining how to interact with the API.

4. SOAP processor:

   • This is the software component that processes SOAP messages.

   • It parses the XML document, extracts the relevant data, and performs the requested operation.

There is also the SOAP Endpoint, which is the URL where the SOAP service can be accessed, and the XML Schema (XSD), which defines the structure and data types used in the SOAP message's XML.

Operation Overview

SOAP APIs operate by encapsulating data within an XML-based structure defined by a SOAP Envelope, which contains both a Header for metadata and a Body for the actual request or response information. The Body carries the exchange data, while a WSDL document serves as a contract detailing the service's operations, message formats, and data types.

A SOAP Processor then parses the XML, extracts relevant data, and executes the requested operations according to rules defined by an accompanying XML Schema (XSD). Communication with the service occurs through a specific SOAP Endpoint, ensuring a standardised, interoperable framework for web service interactions.

Practical Examples and Real-world Use Cases

To illustrate SOAP APIs and how they work practically, let’s consider a SOAP-based Banking Service API that provides secure operations for managing accounts and transactions. SOAP APIs use XML messaging to ensure secure and structured communication between systems. Creating a SOAP API and XML messaging is beyond the scope of this article, so here we’ll just focus on the Request and Response logic.

How it works:

• Retrieve account information: The client sends an XML request to fetch a user’s account details:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bank="http://example.com/bank">
   <soapenv:Header/>
   <soapenv:Body>
      <bank:GetAccountDetails>
         <bank:AccountNumber>123456789</bank:AccountNumber>
      </bank:GetAccountDetails>
   </soapenv:Body>
</soapenv:Envelope>

The server responds with an XML message containing the account details:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <GetAccountDetailsResponse>
         <AccountNumber>123456789</AccountNumber>
         <Balance>5000.00</Balance>
         <Currency>USD</Currency>
      </GetAccountDetailsResponse>
   </soapenv:Body>
</soapenv:Envelope>

• Process a money transfer: The client submits a transfer request with authentication details:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                      xmlns:bank="http://example.com/bank">
       <soapenv:Header/>
       <soapenv:Body>
          <bank:TransferFunds>
             <bank:FromAccount>123456789</bank:FromAccount>
             <bank:ToAccount>987654321</bank:ToAccount>
             <bank:Amount>100.00</bank:Amount>
             <bank:Currency>USD</bank:Currency>
          </bank:TransferFunds>
       </soapenv:Body>
    </soapenv:Envelope>
  

  If successful, the server returns a confirmation response:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
       <soapenv:Body>
          <TransferFundsResponse>
             <Status>Success</Status>
             <TransactionID>TXN987654</TransactionID>
          </TransferFundsResponse>
       </soapenv:Body>
    </soapenv:Envelope>
  

Banks, healthcare providers, and government agencies use SOAP for secure, reliable APIs. Financial institutions process transactions with strict authentication, while healthcare systems exchange patient data under compliance regulations. Airlines rely on SOAP for booking and ticketing, ensuring consistent data integrity across systems.

GraphQL APIs

GraphQL is a query language and runtime for APIs developed by Facebook. It allows clients to request exactly the data they need in a single request, reducing over-fetching and under-fetching.

Key Components

1. Schema: This is the heart of a GraphQL API. It defines the structure of your data, including the types of objects, their fields, and their relationships. It acts as a contract between the client and server, specifying what data can be queried.

2. Types: These define the structure of objects in your data. They specify the fields that each object has and the data types of those fields.

3. Fields: These are the individual pieces of data that can be queried on an object.

4. Queries: These are requests from the client to retrieve data. They specify the fields that the client wants to recover.

5. Mutations: These are requests from the client to modify data (create, update, or delete).

6. Resolvers: These are functions that fetch the data for each field in the schema. They connect the GraphQL schema to the underlying data sources.

7. Subscriptions: These enable real-time updates. Clients can subscribe to specific events, and the server will push updates whenever they occur.

Operation Overview

GraphQL defines a schema that specifies available data types and their relationships. Clients then construct queries or mutations that precisely request the needed data fields. The GraphQL server processes these requests, using resolvers to fetch data from backend sources.

The server validates the request against the schema, executes the resolvers, and returns a JSON response containing only the requested data. Clients can establish subscriptions for real-time updates, enabling the server to push data changes as they occur. This approach minimises over-fetching and under-fetching, improving efficiency and flexibility in data retrieval.

Practical Examples and Real-world Use Cases

Let’s explore how GraphQL APIs work practically by considering an E-commerce API powered by GraphQL. This API can efficiently fetch product details, reviews, and stock availability. The server is created using NodeJS and Apollo Server. Creating the server is beyond the scope of this article, so we will focus on the Schema (how a relational database is structured and visually represented) and the Request and Response logic.

1. Schema:

# Schema (schema.graphql)

type Product {
  id: ID!
  name: String!
  description: String
  price: Float!
  inventory: Int!
  category: String!
}

type Query {
  product(id: ID!): Product
  products(category: String): [Product!]!
}

type Mutation {
  createProduct(name: String!, description: String, price: Float!, inventory: Int!, category: String!): Product!
  updateProductInventory(id: ID!, inventory: Int!): Product!
}

The Schema defines the data types (Product, Query, Mutation) and specifies the available queries (product, products), and mutations (createProduct, updateProductInventory). It uses the GraphQL type system (String, Int, Float, ID, [ ], !)

2. Requests and Response

   • Fetching product data - A client requests specific product fields (for example, name, price, and description):

       query {
         product(id: "123") {
           name
           price
           description
         }
       }
     

     If it is successful, the server responds with only the requested data:

       {
         "data": {
           "product": {
             "name": "Wireless Headphones",
             "price": 99.99,
             "inStock": true
           }
         }
       }
     

   • Create a new product:

       mutation {
         createProduct(name: "Mouse", price: 30, inventory: 100, category: "Electronics") {
           id
           name
           price
         }
       }
     

   • Update product information:

       mutation {
         updateProduct(id: "123", price: 89.99) {
           name
           price
         }
       }
     

     If successful, the server returns the updated details:

       {
         "data": {
           "updateProduct": {
             "name": "Wireless Headphones",
             "price": 89.99
           }
         }
       }
     

Companies like Facebook and Shopify use GraphQL for efficient, flexible APIs. E-commerce and social apps fetch only needed data, reducing over-fetching. Mobile apps optimize performance, while analytics tools aggregate complex data seamlessly.

gRPC APIs

Remote Procedure Call (gRPC) is a high-performance RPC framework that serialises structured data using HTTP/2 and Protocol Buffers. It supports synchronous and asynchronous communication and features like streaming.

HTTP/2 is the latest evolution of HTTP, designed with exciting features like binary framing, multiplexing, header compression, and server push to boost performance and reduce latency. gRPC takes full advantage of these capabilities, enabling quick, efficient, and simultaneous communication, which makes it a perfect fit for microservices and real-time applications.

Key Components

1. Service definition: This is defined in a .proto file. It specifies the services offered and the RPC methods available, acting as the contract between client and server.

2. Messages are data structures defined using Protocol Buffers, which efficiently serialise and deserialise data between systems.

3. Stubs: Auto-generated client and server code that lets the client call remote methods as if they were local and enables the server to implement the service logic.

4. Channels: These manage the connection between client and server, handling the underlying network communication.

5. RPC methods: gRPC supports different types of calls, including unary (single request-response), client streaming, server streaming, and bidirectional streaming, each suited for different use cases.

6. Interceptors and metadata: These provide mechanisms to add extra functionality, such as authentication, logging, and error handling, by attaching metadata to RPC calls.

Operation Overview

gRPC enables developers to define service contracts and message types in a .proto file with Protocol Buffers, serving as a blueprint for available RPC methods. The code generator produces client and server stubs, allowing remote procedures to be invoked like local functions, while channels manage HTTP/2-based network communication.

It supports unary, client streaming, server streaming, and bidirectional streaming for different data exchange patterns. Also, interceptors and metadata can be integrated for tasks like authentication and logging, keeping the system robust, secure, and efficient.

Practical Examples and Real-world Use Cases

Let’s consider a ride-sharing application that uses gRPC for fast communication between clients (mobile apps) and backend services. gRPC uses binary serialization via protocol buffers (Protobuf) instead of text-based formats like JSON or XML. This makes network communication significantly faster and more efficient.

1. The .proto file defines the API structure:

syntax = "proto3";

service RideService {
  rpc RequestRide(RideRequest) returns (RideResponse);
  rpc StreamRideUpdates(RideUpdateRequest) returns (stream RideUpdate);
}

message RideRequest {
  string user_id = 1;
  string pickup_location = 2;
  string destination = 3;
}

message RideResponse {
  string ride_id = 1;
  string driver_name = 2;
  string car_model = 3;
}

message RideUpdate {
  string ride_id = 1;
  string status = 2;
  string driver_location = 3;
}

message RideUpdateRequest {
  string ride_id = 1;
}

When a client sends a RideRequest, it is serialized into a compact binary format using Protobuf. This reduces payload size, speeds up transmission, and improves efficiency. The server deserializes it back into a structured object before processing.

2. Request and Response:

   • Requesting a ride: The client sends a ride request with the click of a button that entails:

       {
         "user_id": "U123",
         "pickup_location": "Central Park",
         "destination": "Times Square"
       }
     

     The server responds with driver details:

       {
         "ride_id": "R456",
         "driver_name": "John Doe",
         "car_model": "Toyota Prius"
       }
     

     You must be wondering why the requests and responses are displayed in JSON since gRPC doesn’t use text-based formats like JSON and XML. The compressed binary stream used in gRPC is not human-readable like JSON. It’s a compact, efficient encoding format that requires Protobuf deserialization under the hood to be understood. In compressed binary stream format, the request or response will look like this:

       08 D2 04 12 0D 43 65 6E 74 72 61 6C 20 50 61 72 6B 1A 0B 54 69 6D 65 73 20 53 71 75 61 72 65
     

   • Streaming ride updates: Once a ride is assigned, the server streams real-time updates to the client:

       {
         "ride_id": "R456",
         "status": "Driver on the way",
         "driver_location": "5th Avenue"
       }
     

Companies use gRPC for high-performance, real-time applications requiring efficient service communication. Tech giants like Google, Netflix, and Dropbox utilize gRPC for scalable microservices. Ride-sharing apps stream live driver locations, while fintech platforms manage secure, low-latency transactions. IoT systems and AI applications depend on gRPC for real-time data exchange and efficient interactions.

How to Choose an API Architecture

Selecting an API architecture involves balancing various factors, including performance, scalability, ease of use, and security, according to your project's specific needs.

REST is known for its simplicity and stateless design, which aids scalability and ease of use, but its security depends mainly on external measures like HTTPS and proper authentication mechanisms.

SOAP, while more complex, provides robust built-in security standards (like WS-Security) and reliable transactional support, making it suitable for enterprise environments.

GraphQL offers efficient data fetching and high performance by allowing clients to request only the data they need. Still, it may require additional security measures such as query depth limiting and proper authentication on the server side.

gRPC delivers exceptional performance and is ideal for microservices with real-time data needs. It leverages HTTP/2 and TLS for secure, efficient communication, though it has a steeper learning curve.

The table below summarises the features and tradeoffs between these architectures:

Conclusion and Future Trends

APIs have become a mainstay in modern software development, facilitating seamless communication and data exchange between diverse applications. Their impact is undeniable, from public APIs that fuel innovation to private APIs that streamline internal processes.

Understanding the various API architectures, like REST, SOAP, GraphQL, and gRPC, empowers developers to select the optimal approach for their specific needs, balancing performance, scalability, and ease of use.

Looking ahead, the API landscape is set for exciting changes. With AI-driven APIs, decentralized architectures, and improved security measures, we’ll see new ways to build and interact with software. The continuous evolution of API standards and the growth of low-code/no-code platforms are making API development more accessible to everyone.