SDK v1 Reference Documentation

Welcome to the SDK v1 Documentation

This document provides comprehensive information on how to use and integrate with the Software Development Kit (SDK) version 1.0. Our SDK allows you to interact with our platform's core functionalities programmatically, enabling you to build powerful applications and streamline your workflows.

Whether you are a seasoned developer or just starting, this guide will walk you through the essential concepts, API endpoints, and best practices for a smooth integration experience.

Getting Started

Before you begin, ensure you have the necessary prerequisites:

Installation

You can typically install the SDK using your preferred package manager. For example, using npm:

npm install @yourcompany/sdk-v1

Initialization

Initialize the SDK with your API key:


import SDK from '@yourcompany/sdk-v1';

const sdk = new SDK({
  apiKey: 'YOUR_API_KEY'
});

Core Concepts

Understanding these fundamental concepts will help you leverage the SDK effectively.

Authentication

All requests to the SDK must be authenticated. Authentication is handled via an API key provided during SDK initialization. The SDK automatically includes your API key in the request headers.

Data Models

Our API uses a consistent data model for resources. Key entities include:

For detailed schema definitions, please refer to the API Reference section.

Error Handling

The SDK provides robust error handling. When an error occurs, the SDK will throw an exception or return a structured error object. Common error codes include:

Code Message Description
400 Bad Request The request was malformed or invalid.
401 Unauthorized Authentication failed or missing API key.
403 Forbidden You do not have permission to perform this action.
404 Not Found The requested resource could not be found.
500 Internal Server Error An unexpected error occurred on the server.

API Reference

This section details the available methods and their parameters for interacting with the SDK.

Users

sdk.users.get(userId)

GET /users/{userId}

Retrieves details for a specific user.

Parameters:
  • userId (string, required): The unique identifier of the user.
Returns:

A promise that resolves to a User object.

sdk.users.list(options)

GET /users

Retrieves a list of users. Supports pagination and filtering.

Parameters:
  • options (object, optional): Configuration for pagination and filtering.
    • page (number): The page number to retrieve (default: 1).
    • limit (number): The number of items per page (default: 20).
    • status (string): Filter by user status (e.g., 'active', 'inactive').
Returns:

A promise that resolves to an object containing a list of User objects and pagination metadata.

Projects

sdk.projects.create(projectData)

POST /projects

Creates a new project.

Parameters:
  • projectData (object, required): Data for the new project.
    • name (string, required): The name of the project.
    • description (string, optional): A detailed description.
Returns:

A promise that resolves to the newly created Project object.

sdk.projects.get(projectId)

GET /projects/{projectId}

Retrieves a specific project by its ID.

Parameters:
  • projectId (string, required): The ID of the project to retrieve.
Returns:

A promise that resolves to a Project object.

Tasks

sdk.tasks.list(projectId, options)

GET /projects/{projectId}/tasks

Retrieves a list of tasks for a given project. Supports filtering and sorting.

Parameters:
  • projectId (string, required): The ID of the project.
  • options (object, optional): Configuration for pagination, filtering, and sorting.
    • status (string): Filter by task status (e.g., 'open', 'in_progress', 'completed').
    • assigneeId (string): Filter by assignee.
    • sortBy (string): Field to sort by (e.g., 'dueDate', 'createdAt').
    • sortOrder (string): 'asc' or 'desc' (default: 'asc').
Returns:

A promise that resolves to an object containing a list of Task objects.

sdk.tasks.create(projectId, taskData)

POST /projects/{projectId}/tasks

Creates a new task within a specified project.

Parameters:
  • projectId (string, required): The ID of the project.
  • taskData (object, required): Data for the new task.
    • title (string, required): The title of the task.
    • description (string, optional): A detailed description.
    • dueDate (string, optional): The due date in ISO format.
    • assigneeId (string, optional): The ID of the user assigned to the task.
Returns:

A promise that resolves to the newly created Task object.

sdk.tasks.update(taskId, taskData)

PUT /tasks/{taskId}

Updates an existing task.

Parameters:
  • taskId (string, required): The ID of the task to update.
  • taskData (object, required): Fields to update (e.g., status, dueDate).
Returns:

A promise that resolves to the updated Task object.

sdk.tasks.delete(taskId)

DELETE /tasks/{taskId}

Deletes a task.

Parameters:
  • taskId (string, required): The ID of the task to delete.
Returns:

A promise that resolves when the task is successfully deleted.

Reporting

sdk.reporting.getProjectSummary(projectId, options)

GET /reporting/projects/{projectId}/summary

Generates a summary report for a project.

Parameters:
  • projectId (string, required): The ID of the project.
  • options (object, optional): Report configuration.
    • startDate (string): Start date for the report (ISO format).
    • endDate (string): End date for the report (ISO format).
Returns:

A promise that resolves to a Project Summary report object.

Changelog

v1.0.0 (2023-01-15)

Support

If you encounter any issues or have questions not covered in this documentation, please visit our Developer Portal or contact our support team at support@yourcompany.com.