Quick Start

Get up and running with Kable in under 15 minutes

This Quick Start guide will walk you through the steps to add Kable to your API. By the end of this tutorial you will have metrics, billing, and payments automated in your product.

Estimated completion time: 15 minutes

🚧

Throughout this tutorial, we'll consider a sample use case, a messaging API company called Mailman. In each step we'll consider what Mailman might implement, but you should feel free to adapt the tutorial to your own use case.

  1. Sign up for Kable

First, create a free account on Kable. You can get started by signing up here.

  1. Create a Dimension

📘

Dimensions are metrics that are meaningful to your business.

Define a new metric from the Dimensions tab in your dashboard.

🚧

Mailman might create a dimension called "Text Message" with a key of messageId. This would allow Mailman to do things like track how many text messages were sent by each of its customers in a given month, configure dashboards to show a time-series of sent text messages, and set up pricing plans on a per text message basis.

You can learn more about defining dimensions here.

  1. Create a Plan

📘

Plans define pricing and control how customers are billed each month.

Create a plan from the Plans tab in your dashboard.

🚧

Let's say Mailman wanted to charge $0.10 per text message. Mailman might set up a plan based on the count of text messages per month, with unit pricing of $0.10 each.

For more information about plans or for details on how to set up complex pricing scenarios, check out the plans section of the docs.

  1. Create a Customer

📘

Customers are the developers, applications, or businesses who consume your API.

You can create customers from the Customers tab in your dashboard, or programmatically through the create a customer API.

The Client ID (clientId) you set on each customer should correspond to some unique identifier in your application. You'll use this identifier later when recording usage events in Kable.

While you're here, you may also add the pricing plan you created in the last step to your new customer. (This can also be done programmatically through the add customer plan API.)

  1. Integrate your API

👍

You can find step-by-step instructions for integrating Kable into your application in the Recipes section of the documentation.

Download an SDK

First, download the Kable SDK for your programming language of choice. You can find detailed instructions for each library we support later in the docs.

📘

If we do not yet support a library for your programming language, please let us know. In the meantime, you can integrate directly with the API.

Configure Kable in your API

To configure the library, SDK, or API, you'll need Kable API keys. You can generate API keys from the Company tab in your dashboard. If you don't have one already, generate a Test Environment Key for yourself.

Always treat API keys like passwords -- store them somewhere secure and do not share them with anyone.

With a library installed and API keys created, you can add Kable to your API. A properly-configured Kable instance may look something like:

const { Kable } = require('kable-node-express');

const kable = new Kable({
  kableClientId: '<YOUR_KABLE_CLIENT_ID>',
  kableClientSecret: '<YOUR_KABLE_CLIENT_SECRET>',
  baseUrl: 'https://test.kable.io',
  debug: true
});
from kable_python_flask import Kable

kable = Kable({
  'kable_client_id': '<YOUR_KABLE_CLIENT_ID>',
  'kable_client_secret': '<YOUR_KABLE_CLIENT_SECRET>',
  'base_url': 'https://test.kable.io',
  'debug': True
})
import ("github.com/Kable-io/kable-go")

var kableClient *kable.Kable = kable.New(
    &kable.KableOptions{
        KableClientId:     "<YOUR_KABLE_CLIENT_ID>",
        KableClientSecret: "<YOUR_KABLE_CLIENT_SECRET>",
        Debug:             true,
        MaxQueueSize:      20,
    })

🚧

When first getting started, we suggest you enable debug logging in your Kable configuration. This will cause Kable to print log lines to your console upon application startup so you can confirm your configuration is correct before moving forward.

Record Metrics

Finally, we'll record some usage data from your API. We'll use kable.record (or the API directly) to ingest usage events into Kable.

Include the clientId you defined for your customer above, as well as any dimension metrics you might want to track in the payload of the request.

🚧

As an example, Mailman's implementation might look something like the snippet below:

app.post('/api/messages/send', function(req, res) {
  kable.record({ 
    clientId: 'yourcompanyuser_1234567890', 
    messageId: 'msg_ABC123XYZ456'
  });
  // ...
  res.json({ message: 'Message sent!' });
});
@app.post('/api/messages/send')
def send_message_api():
    kable.record({ 
      "clientId": "yourcompanyuser_1234567890", 
      "messageId": "msg_ABC123XYZ456"
    })
    # ...
    return jsonify({ 'message': 'Message sent!' })
func sendMessageApi(w http.ResponseWriter, r *http.Request) {
    kableClient.Record(kable.Event{
        ClientId: "yourcompanyuser_1234567890",
        Data:     map[string]interface{}{"messageId": "msg_ABC123XYZ456"},
    })
    json.NewEncoder(w).Encode(map[string]string{"message": "Message sent!"})
}
  1. Next Steps

Congratulations, you're done! Your API is now set up to use Kable. If you jump back into your dashboard you'll see usage metrics flowing into Kable as your API is called.

As follow up, you may choose to create threshold alerts, subscribe to webhooks, define additional dimensions, create additional pricing plans, or enhance your integration with Kable by programmatically creating customers and recording metrics. You may also want to embed Kable dashboards within your developer portal or Connect to Stripe to enable automatic invoicing of your customers. There are further instructions for each of these within the docs.

👍

If after working through this guide you'd like to schedule an onboarding session with someone from Kable, feel free to reach out and we'll get in touch to schedule onboarding.

  1. Conclusion

Once you've tested your integration in the Test environment you're ready to generate Live keys and deploy to production. When you're ready to go live, let us know -- we offer free pricing strategy and best practices consultations for each of our customers.

We're always searching for ways to improve our documentation and help our customers. If you have any thoughts about how we can improve or how Kable can help you scale your business, please let us know!

📘

Kable as an Authentication Provider

Some customers choose to use Kable to authenticate their API in addition to tracking usage metrics and managing pricing and invoicing.

Kable as an authentication provider is not covered in this quick start -- for an overview of how to set this up, read more here.