api-res-formatter

API Response Formatter for GitHub

A standardized API response formatter built to ensure consistency and clarity in GitHub-integrated application responses. This formatter wraps success and error responses in a predictable structure, making it easier for clients and developers to handle API interactions effectively.

---

Table of Contents

• Introduction
• Installation
• Usage
• Response Structure
  • Success Format
  • Error Format
• Examples
• Features
• Configuration
• Dependencies
• Troubleshooting
• Contributors
• License
• Conclusion

---

Introduction

When building APIs that interact with GitHub or its ecosystem, maintaining a clean and uniform response format is crucial for debugging, monitoring, and client development. The API Response Formatter is a plug-and-play middleware or utility function that ensures every outgoing response follows a predictable schema, including HTTP status codes, messages, data payloads, and error descriptions.

This utility is ideal for RESTful APIs, GitHub webhook handlers, or GitHub Actions that return JSON responses.

---

Installation

Install via npm:

npm install api-response-formatter

Or with yarn:

yarn add api-response-formatter

---

Usage

Import and use in your application:

JavaScript / Node.js (Express example)

const express = require('express');
const { formatSuccess, formatError } = require('github-api-response-formatter');

const app = express();

app.get('/status', (req, res) => {
  const data = { status: 'OK', timestamp: new Date() };
  return res.status(200).json(formatSuccess(data, 'Status fetched successfully.'));
});

app.get('/error', (req, res) => {
  const errorDetails = { code: 'NOT_FOUND', reason: 'Item does not exist' };
  return res.status(404).json(formatError(errorDetails, 'Requested resource not found.'));
});

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

---

Response Structure

Success Format

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    // your payload here
  },
  "timestamp": "2025-05-03T12:34:56.789Z"
}

Error Format

{
  "success": false,
  "message": "Resource not found.",
  "error": {
    "code": "NOT_FOUND",
    "details": "The specified repository does not exist or access is denied."
  },
  "timestamp": "2025-05-03T12:34:56.789Z"
}

---

Examples

GitHub Webhook Handler

app.post('/webhook', (req, res) => {
  try {
    // Process GitHub event
    return res.json(formatSuccess(null, 'GitHub webhook processed.'));
  } catch (err) {
    return res.status(500).json(formatError({ code: 'WEBHOOK_ERROR', details: err.message }, 'Failed to process webhook.'));
  }
});

API Response with Custom Status Code

return res.status(201).json(formatSuccess({ id: 123 }, 'New repository metadata created.'));

---

Features

• ✅ Uniform success and error structures
• 🧪 Easy to test and log
• 🔒 Timestamp included for audit trails
• 🔁 Compatible with REST APIs, GitHub Actions, and Webhooks
• ⚙️ Extendable with custom fields

---

Configuration

No configuration is required by default.

Optional overrides (if supported in the future):

formatSuccess(data, message, customFields);
formatError(errorObject, message, customFields);

You can inject custom metadata into responses via customFields.

---

Dependencies

• Node.js ≥ 12.x
• (Optional) Express.js for usage examples

No third-party dependencies unless using the formatter within a specific framework.

---

Troubleshooting

Issue	Solution
Timestamps are incorrect	Ensure server timezone is set correctly or handle in client-side logic.
Error format not as expected	Verify that error object contains both code and details.
No response returned	Confirm that res.status().json() is called in your controller logic.

---

Contributors

• Bhadra Mohit — Creator & Maintainer

Feel free to open issues or submit pull requests!

---

License

This project is licensed under the MIT License.

---

Conclusion

API Response Formatter provides a clean, professional, and standardized way to structure your API outputs, improving development efficiency and debugging clarity across all GitHub-integrated services. Lightweight and easy to integrate, it ensures that both humans and machines can reliably interpret your API responses.