Search by Algolia
What is end-to-end AI search?
ai

What is end-to-end AI search?

Simplicity is critical for search engines, but building one that enables that simplicity is complex.  Over the last 20+ years ...

Abhijit Mehta

Director of Product Management

Comparing AI search solutions in a crowded market landscape
ai

Comparing AI search solutions in a crowded market landscape

Many new AI-powered search solutions have been released this year, and each promises to provide great results, but as ...

Andy Jones

Marketing Campaign Production Manager

What is B2B ecommerce? Everything you need to know
e-commerce

What is B2B ecommerce? Everything you need to know

When you think of “customer experience,” what comes to mind? People, right? Specifically, consumers. Retail customers. That’s easy; the ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is ecommerce merchandising? Key components and best practices
e-commerce

What is ecommerce merchandising? Key components and best practices

A potential customer is about to land on the home page of your ecommerce platform, curious to see what cool ...

Catherine Dee

Search and Discovery writer

AI-powered search: From keywords to conversations
ai

AI-powered search: From keywords to conversations

By now, everyone’s had the opportunity to experiment with AI tools like ChatGPT or Midjourney and ponder their inner ...

Chris Stevenson

Director, Product Marketing

Vector vs Keyword Search: Why You Should Care
ai

Vector vs Keyword Search: Why You Should Care

Search has been around for a while, to the point that it is now considered a standard requirement in many ...

Nicolas Fiorini

Senior Machine Learning Engineer

What is AI-powered site search?
ai

What is AI-powered site search?

With the advent of artificial intelligence (AI) technologies enabling services such as Alexa, Google search, and self-driving cars, the ...

John Stewart

VP Corporate Marketing

What is a B2B marketplace?
e-commerce

What is a B2B marketplace?

It’s no secret that B2B (business-to-business) transactions have largely migrated online. According to Gartner, by 2025, 80 ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

3 strategies for B2B ecommerce growth: key takeaways from B2B Online - Chicago
e-commerce

3 strategies for B2B ecommerce growth: key takeaways from B2B Online - Chicago

Twice a year, B2B Online brings together industry leaders to discuss the trends affecting the B2B ecommerce industry. At the ...

Elena Moravec

Director of Product Marketing & Strategy

Deconstructing smart digital merchandising
e-commerce

Deconstructing smart digital merchandising

This is Part 2 of a series that dives into the transformational journey made by digital merchandising to drive positive ...

Benoit Reulier
Reshma Iyer

Benoit Reulier &

Reshma Iyer

The death of traditional shopping: How AI-powered conversational commerce changes everything
ai

The death of traditional shopping: How AI-powered conversational commerce changes everything

Get ready for the ride: online shopping is about to be completely upended by AI. Over the past few years ...

Aayush Iyer

Director, User Experience & UI Platform

What is B2C ecommerce? Models, examples, and definitions
e-commerce

What is B2C ecommerce? Models, examples, and definitions

Remember life before online shopping? When you had to actually leave the house for a brick-and-mortar store to ...

Catherine Dee

Search and Discovery writer

What are marketplace platforms and software? Why are they important?
e-commerce

What are marketplace platforms and software? Why are they important?

If you imagine pushing a virtual shopping cart down the aisles of an online store, or browsing items in an ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is an online marketplace?
e-commerce

What is an online marketplace?

Remember the world before the convenience of online commerce? Before the pandemic, before the proliferation of ecommerce sites, when the ...

Catherine Dee

Search and Discovery writer

10 ways AI is transforming ecommerce
e-commerce

10 ways AI is transforming ecommerce

Artificial intelligence (AI) is no longer just the stuff of scary futuristic movies; it’s recently burst into the headlines ...

Catherine Dee

Search and Discovery writer

AI as a Service (AIaaS) in the era of "buy not build"
ai

AI as a Service (AIaaS) in the era of "buy not build"

Imagine you are the CTO of a company that has just undergone a massive decade long digital transformation. You’ve ...

Sean Mullaney

CTO @Algolia

By the numbers: the ROI of keyword and AI site search for digital commerce
product

By the numbers: the ROI of keyword and AI site search for digital commerce

Did you know that the tiny search bar at the top of many ecommerce sites can offer an outsized return ...

Jon Silvers

Director, Digital Marketing

Using pre-trained AI algorithms to solve the cold start problem
ai

Using pre-trained AI algorithms to solve the cold start problem

Artificial intelligence (AI) has quickly moved from hot topic to everyday life. Now, ecommerce businesses are beginning to clearly see ...

Etienne Martin

VP of Product

Looking for something?

facebookfacebooklinkedinlinkedintwittertwittermailmail

A product-based JavaScript API client should be able to run in the browser, with direct front-end DOM access, as well as in a node environment, to access back-end servers and services.

Additionally, a product-based API client should provide exhaustive and easy access to all features of the application it serves. And it should keep up-to-date with every new feature.

Finally, an API client should add extra value to the application, by adding such functionality as:

  • Retry logic, to sidestep network or any other momentary glitch or timeout
  • Rate-limits and throttling strategies, to reduce server load and usage costs 
  • Batch processing, where the API performs a set of actions to accomplish a single common task
  • And other helper functionality 
  • Friendly view of underlying Rest API

What is a product-based API client?

An API (application programming interface) is not just a wrapper; it’s a separate, light-weight application that enables developers to interact with a full-featured software platform.

A product-based API is an API that a company sells as a product. Google sells the Google Maps API, Stripe sells a financial API, and we sell a Search API. 

A product-based API client is an API that comes in different programming languages, frameworks, and JavaScript flavors. Our clients sit on top of different REST API endpoints. 

By offering an API client in a developer’s own language, they get the benefit of:

  • Faster onboarding to implement the basic and advanced features of an application
  • Simpler integration into their own codebases
  • Large amounts of code already written for them, including retries, throttling, and batching

The best API design also tries to limit the amount of boilerplate code needed to instantiate, use, or parameterize an API method.

We can name a few other defining characteristics of a product-based API client:

  • Small code size
  • Low or no dependencies
  • Flexible customization with smart parameters 
  • Intuitive DX in the naming and usage of requests and responses (improvement over Rest API)
  • Thorough API documentation and tutorials
  • Non-breaking versioning
  • Authentication with API keys or tokens
  • Simple and universal data exchanges with JSON
  • Keeping up to date with changes and best practices in the underlying programming languages and technologies

How to improve an API product from version to version

First a word about process: We have over 10,000 customers using our API clients. With that kind of usage, we are in a good position to fine-tune our APIs based on customer support tickets, chats, and usage statistics in our logs. 

However, an even greater source of truth is our own engineers. Our APIs are not just used by our customers. Our Dashboard uses our JavaScript, PHP, Ruby, and other API clients; we have inhouse use cases that implement our API clients; our client-facing tech support teams create demos, prototypes, and solutions using our API clients. With all that API testing and internal usage, we know first-hand the pain points and positive aspects of our API clients. 

With all that feedback, every release includes:

  • Refactoring the interface and the code behind (non-breaking) to keep up with the changing standards and evolutions of the underlying technology. For example, our newest version of our JavaScript client supports ES6 and TypeScript. 
  • Improving the DX for all kinds of developers – experienced, beginners, domain experts.
  • Targeting more use cases. New or existing methods to better address certain use cases, sometimes even adopting the jargon of an industry.  
  • Generating a common interface across all API languages. Many customers switch between different languages. Having a common interface helps with that. Using JSON also helps.

Some upgrades we’ve made to our JavaScript API client

For SaaS companies like ours, a JavaScript API client is critical, because of its ability to request services directly from our cloud servers without requiring customers to go though their own back-end servers. Among other things, client-side API requests improve the response time of the new API and simplify the front-end code on the front end. Because of these benefits, our JavaScript API is our most used client.

With that in mind, JavaScript APIs have to manage the challenges of client-side application development, as well as the particularities of the JavaScript language and its flavors like React, Vue, and Angular. 

Here are some improvements we’ve made recently:

Support for both require and import, and default and lite versions

// For the default version
const algoliasearch = require('algoliasearch');
 
// For the default version
import algoliasearch from 'algoliasearch';
 
// For the search only version
import algoliasearch from 'algoliasearch/lite';

Parameterized instantiation

We started with a simple instantiation – client application id and the API key:

const algoliasearch = algoliasearch('YourApplicationID', 'YourAdminAPIKey');

Then we added a third parameter, allowing the developer to customize a number of additional features:

const algoliasearch = algoliasearch(
   'YourApplicationID',
   'YourSearchOnlyAPIKey',
{
   timeouts: {
       connect: 1,
       read: 2,
       write: 30,
   },
   requester: createBrowserXhrRequester(),
   logger: createConsoleLogger(LogLevelEnum.Error),
   responsesCache: createInMemoryCache(),
   requestsCache: createInMemoryCache({ serializable: false }),
   hostsCache: createFallbackableCache({
       caches: [
           createBrowserLocalStorageCache({ key: `${version}-${appId}` }),
           createInMemoryCache(),
       ],
   }),
});

As you can see, the third parameter allows developers to define:

  • Unique timeouts
  • The behavior of requesters
  • Customizations for node requests or a browser environment
  • Log callbacks
    • Logging enables us to follow the lifecycle of a client, to record and then analyze API activity.
    • Recording API activity helps us improve the usage of an API in future versions. It also enables us to reduce pricing by removing certain common usages from the costs.
    • Also, by allowing developers to send us their own logging methods, we can store the information they think is important, thus improving the quality of our own logs.
  • Response caching
    • Developers can manage their own throttling, for example.
    • They can disable our response caching, as well.
    • They can manage local storage, preserving the state of search even after a browser refreshes.
  • Request caching
    • Allows promise sharing, for example.

Reduced size of the JavaScript

Make the client tree shakeable:

// Tree shakable ( 1 kb, dead code elimination )
// list the methods you use and don’t include the code of any other method  
const client = createSearchClient({
   // ..
   methods: { search }
}); 

Customized requests 

Experts sometimes require a non-opinionated, open request to handle unexpected use cases. For example, developers can pass read/write requests to cover what is not in the API:

client.transporter.read ({
   path: '',
   verb: 'GET'
});

Note on logging: when we log these customized requests, we can take that information to create new methods in the future.

Reducing dependencies to zero

You can achieve zero-dependency simply by following JavaScript standards and using Typescript.

Batching common, multi-tasked operations

Instead of a single Save() method, we added more robust methods like replaceAllObjects(), reindex(), copyIndex(). This helps ensure best practices in such data-sensitive methods. Additionally, we’ve written all the code that manages retries and zero-downtime logic.

Typescript support

javascript typescript

Managing the release schedule

Last but not least, a product-based API client must follow the best strategies for testing and release practices. We’ll leave testing to another blog, but here’s the overall strategy we use for our release cycle:

  • Release a beta version for internal use cases, applications, and demos
  • Work with the Docs team to standardize and document the DX
  • Help upgrade products that rely on our API clients
  • Release a final beta to a handful of customers
  • Release the stable version, along with the updated Docs
  • Promote and encourage migration via Support calls, blog posts, and social media
About the author
Peter Villani

Sr. Tech & Business Writer

linkedinmediumtwitter

Recommended Articles

Powered byAlgolia Algolia Recommend

What is an API?
product

Catherine Dee

Search and Discovery writer

Ruby Client v2 is out!
engineering

Chloé Liban

Software Egineer

Search 101: What is an API key? How does it provide API security?
engineering

Peter Villani

Sr. Tech & Business Writer