windowsworld-api

A comprehensive API client for interacting with the Windows World Cartoon API. This package provides a simple and intuitive way to access the API's endpoints, allowing you to easily retrieve and manipulate data. With support for GET, POST, PUT, and DELETE requests, this package is perfect for developers who want to integrate the Windows World Cartoon API into their applications.

Table of Contents

• Installation
• Usage
• API Reference
• Examples
• Error Handling
• TypeScript Support
• License

Installation

To install windowsworld-api, run the following command:

npm install @windowsworldcartoon/windowsworld-api

Requirements

• Node.js (version 12 or higher)
• npm or yarn

Usage

First, require the module and initialize the API client with your base URL:

const { api } = require('windowsworld-api');

// Initialize with your API base URL
await api.create('https://api.windowsworld.workers.dev');

Once initialized, you can make HTTP requests to the API endpoints.

API Reference

create(baseURL: string): Promise<API>

Initializes the API client with the specified base URL.

• baseURL: The base URL of the API (e.g., 'https://api.windowsworld.workers.dev')

get(path: string, params?: object, headers?: object): Promise<Object>

Makes a GET request to the API.

• path: The endpoint path (e.g., '/api/groups')
• params: Optional query parameters as an object
• headers: Optional headers as an object

post(path: string, data?: object, params?: object, headers?: object): Promise<Object>

Makes a POST request to the API.

• path: The endpoint path
• data: Optional request body data
• params: Optional query parameters
• headers: Optional headers as an object

put(path: string, data?: object, params?: object, headers?: object): Promise<Object>

Makes a PUT request to the API.

• path: The endpoint path
• data: Optional request body data
• params: Optional query parameters
• headers: Optional headers as an object

delete(path: string, params?: object, headers?: object): Promise<Object>

Makes a DELETE request to the API.

• path: The endpoint path
• params: Optional query parameters
• headers: Optional headers as an object

Examples

Basic GET Request

const { api } = require('windowsworld-api');

async function getGroups() {
    await api.create('https://api.windowsworld.workers.dev');
    try {
        const headers = { 'Authorization': 'Bearer your-token' };
        const response = await api.get('/api/groups', {}, headers);
        console.log(response.data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

POST Request with Data

const { api } = require('windowsworld-api');

async function createGroup() {
    await api.create('https://api.windowsworld.workers.dev');
    try {
        const newGroup = { name: 'New Group', description: 'A new group' };
        const headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-token' };
        const response = await api.post('/api/groups', newGroup, {}, headers);
        console.log('Created:', response.data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

PUT Request to Update

const { api } = require('windowsworld-api');

async function updateGroup(id) {
    await api.create('https://api.windowsworld.workers.dev');
    try {
        const updatedData = { name: 'Updated Group' };
        const response = await api.put(`/api/groups/${id}`, updatedData);
        console.log('Updated:', response.data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

DELETE Request

const { api } = require('windowsworld-api');

async function deleteGroup(id) {
    await api.create('https://api.windowsworld.workers.dev');
    try {
        const response = await api.delete(`/api/groups/${id}`);
        console.log('Deleted successfully');
    } catch (error) {
        console.error('Error:', error.message);
    }
}

Using with Express

const express = require('express');
const { api } = require('windowsworld-api');

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

(async () => {
    await api.create('https://api.windowsworld.workers.dev');

    app.get('/groups', async (req, res) => {
        try {
            const response = await api.get('/api/groups');
            res.json(response.data);
        } catch (error) {
            res.status(500).json({ error: error.message });
        }
    });

    app.post('/groups', async (req, res) => {
        try {
            const response = await api.post('/api/groups', req.body);
            res.json(response.data);
        } catch (error) {
            res.status(500).json({ error: error.message });
        }
    });

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

Error Handling

The API client throws APIError instances for failed requests. Each error includes:

• message: A descriptive error message
• data: Additional error details (e.g., request path, parameters, response data)

const { api, APIError } = require('windowsworld-api');

try {
    await api.create('https://api.windowsworld.workers.dev');
    const response = await api.get('/invalid-endpoint');
} catch (error) {
    if (error instanceof APIError) {
        console.error('API Error:', error.message);
        console.error('Details:', error.data);
    } else {
        console.error('Other Error:', error.message);
    }
}

Common error scenarios:

• Missing base URL (call create() first)
• Invalid or missing path parameter
• Network errors (connection issues, timeouts)
• HTTP errors (4xx, 5xx status codes)

TypeScript Support

Type definitions are included. Import the module in TypeScript projects:

import { api, API } from 'windowsworld-api';

async function example() {
    await api.create('https://api.windowsworld.workers.dev');
    const response = await api.get('/api/groups');
    // response is typed as Promise<any>
}

License

This project is licensed under the ISC License.