From REST to SDK: Getting Started with the lists.do API in 5 Minutes

As developers, we spend an inordinate amount of time manipulating lists. Whether it's sorting user data, filtering product catalogs, or comparing two sets of email addresses, array operations are the bread and butter of modern applications. We write for loops, chain map().filter().reduce(), and build custom functions to handle it all. But what if we're reinventing the wheel, especially when performance and scale become critical?

Enter lists.do, a simple, developer-first API designed to handle powerful list operations as a service. Instead of writing boilerplate code for sorting, filtering, and complex set operations, you can offload the heavy lifting to an optimized and scalable platform.

This guide will show you how to get up and running with the lists.do SDK in just a few minutes.

What is lists.do? A List Management API

At its core, lists.do provides "Lists as a Service." It's a dedicated API for performing common and complex data manipulation tasks. Think of it as a supercharged toolkit for all your array needs. By using a simple API call, you can:

• Compare lists: Find differences, unions, and intersections between multiple datasets.
• Filter and Sort: Perform complex filtering and multi-level sorting on large arrays of objects.
• Transform Data: Map and process items without bogging down your own server.
• Ensure Performance: Handle lists with millions of items asynchronously, leveraging our optimized cloud infrastructure.

The goal is to let you focus on your application's core business logic, not on the nuances of high-performance data manipulation.

Getting Started: The 5-Minute Guide

Let's dive right in by making our first API call. We'll use a common scenario: finding unique contacts from two separate email lists.

Step 1: Install the SDK

First, add the official lists.do JavaScript/TypeScript SDK to your project using your favorite package manager.

npm install @do/sdk

or

yarn add @do/sdk

Step 2: Your First API Call with the diff Operation

The SDK provides a clean and intuitive way to interact with the lists.do REST API. Let's find all the emails that exist in listA but not in listB.

Create a new file and add the following code. You'll need to get your API key from your lists.do dashboard.

import { createClient } from '@do/sdk';

// Initialize the client with your API key
const lists = createClient('YOUR_API_KEY');

// Our two lists of contacts
const listA = ['user1@example.com', 'user2@example.com', 'admin@example.com'];
const listB = ['user2@example.com', 'user3@example.com'];

async function findUniqueContacts() {
  try {
    console.log('Finding items in List A that are not in List B...');
    
    // The diff operation finds the set difference between a source and one or more exclude lists
    const { data, error } = await lists.diff({
      source: listA,
      exclude: [listB] // exclude can be an array of lists
    });

    if (error) {
      throw new Error(error.message);
    }

    console.log('Unique contacts:', data); 
    // Output: Unique contacts: ['user1@example.com', 'admin@example.com']

  } catch (err) {
    console.error('An error occurred:', err);
  }
}

findUniqueContacts();

In just a few lines of code, we performed a set theory difference operation. The lists.diff function took our two arrays and returned only the items present in the source but absent from the exclude list. Imagine doing this with millions of records—the logic remains just as simple, but the performance benefits are immense.

Beyond the diff: Other Powerful Array Operations

The diff operation is just the beginning. The lists.do API is a comprehensive platform for data manipulation. Here are a few other operations you can perform:

• Intersection: Find common items between multiple lists. Perfect for identifying overlapping customers or shared interests.
  await lists.intersect({ sources: [listA, listB] });
• Uniques: Deduplicate a single list to get only the unique items.
  await lists.uniques({ data: messyList });
• Sort: Perform advanced sorting on arrays of objects by one or more keys.
  await lists.sort({ data: users, by: 'lastName', order: 'asc' });
• Filter: Apply complex conditions to filter a list without writing custom loop logic.
  await lists.filter({ data: products, where: { property: 'price', gte: 100 } });

FAQs

Q: Why would I use an API for list operations?

A: Using lists.do abstracts away the complexity of common data manipulation tasks. It allows you to reduce boilerplate code, ensure high performance on large datasets, and focus on your application's core business logic.

Q: How does lists.do handle very large lists?

A: lists.do is built for scale. Operations are executed on our optimized cloud infrastructure, allowing you to process lists with millions of items asynchronously without impacting your own server resources.

Q: Can I integrate lists.do with my current tech stack?

A: Yes. We offer simple REST APIs and developer-friendly SDKs for languages like TypeScript/JavaScript, Python, and Go, making it easy to integrate list operations into any new or existing project.

Stop Reinventing the List

You have better things to do than write another sorting algorithm or custom differ. By leveraging a dedicated list api, you can write cleaner code, build faster, and ensure your application can handle data at any scale.

Ready to simplify your data manipulation logic? Sign up at lists.do to get your free API key and make your first call today.