Serverside API

Introduction

The Kodaris platform has been architected from the ground up with extensibility in mind. From our inception, our core design philosophy has centered on creating a modular system that developers can easily build upon and extend.

Part of what makes our approach unique is our dual API architecture. While many platforms offer external REST APIs for building browser and mobile applications, Kodaris also provides a matching server-side internal api. Every API endpoint available in our Rest API Swagger documentation, also exists as an identical internal API endpoint with matching signatures.

This symmetrical design allows developers to build applications in two distinct ways:

1. External Applications: Traditional integration via our REST API. For example: single page applications, websites, and mobile apps.
2. Platform-Native Applications: Custom server-side solutions built directly on the platform using our server-side API

Benefits of the Server-Side API

Building with our server-side API offers several distinct advantages:

1. Native Integration: Create applications that run on the server and appear completely native to the platform
2. Upgrade Safety: The Kodaris API signatures remain consistent, which means your custom server-side applications continue functioning through platform updates
3. Continuous Innovation: Our architecture enables us to deliver thousands of platform updates annually (with releases every 7 days) without disrupting your custom implementations built using the server-side API
4. Customer-Specific Solutions: By leveraging the server-side API, you can extend and customize the Kodaris platform while maintaining compatibility with our rapid release cycle and our combined future innovations.

Using the Serverside API

To use the server-side API, the SDK provides a fetch interface for making API requests and processing the responses. With the fetch API, you make a request by calling kd.api.fetch() and pass it a request object. The fetch method will return a response object which you can use to check the request status and extract the response data.

Here's a minimal example which uses the serverside api to update the name of a product in the Kodaris system.

var result = kd.api.fetch({
  method: 'PATCH',
  endpoint: '/api/system/product/{productID}',
  queryParams: {
    version: 2
  },
  pathParams: {
    productID: 1
  },
  body: {
    name: 'Dewalt Drill'
  }
});

---> Returns

{
  success: true,
  messages: [],
  errors: [],
  data: {
    productID: 1,
    name: 'Dewalt Drill',
    ... the rest of the product fields
  }
}

Methods

fetch(params)

1. Parameters
   1. params (Object): The configuration for the API request with the following properties:
      1. method (String, required): The HTTP method to use (e.g., 'GET', 'POST', 'PUT', 'DELETE').
      2. endpoint (String, required): The API endpoint to call.
      3. pathParams (Object, optional): Parameters to be substituted in the endpoint path.
      4. queryParams (Object, optional): Query parameters to append to the URL.
      5. version (Number, optional): API version to use. Always use version 2.
      6. body (Any, optional): The request body data.
2. Returns (Object): A response object that contains whether the API request was successful along with any messages, errors, and finally the response data.
3. Example:

// Make an API call to fetch a user
var response = kd.api.fetch({
  method: 'GET',
  endpoint: '/users/{userId}',
  pathParams: {
    userId: 'user_123456'
  },
  queryParams: {
    include: 'profile,preferences'
  }
});

/* Sample Response:
{
  success: true,
  status: 200,
  data: {
    id: "user_123456",
    username: "johndoe",
    email: "john.doe@example.com",
    profile: {
      firstName: "John",
      lastName: "Doe"
    },
    preferences: {
      theme: "dark",
      notifications: true
    },
    createdAt: "2023-01-15T08:30:45Z"
  }
}

// Error response example:
{
  success: false,
  status: 404,
  error: {
    code: "user_not_found",
    message: "The requested user could not be found"
  }
}
*/

// Create a new resource
var createResponse = kd.api.fetch({
  method: 'POST',
  endpoint: '/resources',
  body: {
    name: "New Resource",
    type: "document",
    content: "Resource content goes here"
  }
});

// Update an existing resource
var updateResponse = kd.api.fetch({
  method: 'PUT',
  endpoint: '/resources/{resourceId}',
  pathParams: {
    resourceId: 'res_789012'
  },
  body: {
    name: "Updated Resource Name",
    content: "Updated content goes here"
  }
});