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.