Get started

We recommend the following approach to develop an application with our API.

1. Get an API Key

Create a new API key from your Rebrandly dashboard.
More info about authentication here.
If you haven't done it yet, get your FREE Rebrandly account now.

2. Configure your API client

Within your application/script, you can access Rebrandly Web API via HTTP protocol.
Search for a component able to perform basic HTTP operations, and define GET, POST and DELETE operations in such a way they include following headers:

• Content-Type: application/json
• apikey: YOUR_API_KEY

If you want to use API to interact with your account in the context of a Rebrandly Workspace (ex Team), you need to include an additional HTTP header with your workspace id (See /v1/workspaces):

• workspace: YOUR_WORKSPACE_ID
  Alternatively, you can specify your workspace id via query parameter (syntax: workspace[id]=YOUR_WORKSPACE_ID or via body parameter (workspace property with a Resource reference to the workspace).
  If you do not specify the workspace context, the default workspace (your main workspace) will be used.

3. Manage user identity

📘

One GET to rule them all

This will be your web client proof of concept for HTTP GET operations.

Let's implement a basic operation to get user account details.
Model for accounts is documented in Accounts, while the API call to get account details is documented in the Getting account details section.

We recommend you always get account's details as the first step in your application flow, to understand which features the account's owner has access to, and which limits are in place for that API key or OAuth token.

4. Rebrand your first link

📘

One POST to rule them all

This will be your web client proof of concept for HTTP POSToperations.

Let's implement a basic operation to create a new branded short link.
Model for links is documented in Branded short links, while the API call to create a new link is documented in the Creating a new link section.
A beginner's guide is available as well: Rebrand your first link.

5. Enhance your application

When GET and POST flows are working properly in your Rebrandly web client, you can enrich it with further API operations.

For each API operation you want to perform in your application:

• Include in your application model all object definitions involved (in Models section)
• Include in your application error model, all of the error object definitions involved (in Errors section).
• Include in your application web client, the API operation (GET, POST or DELETE), as well with a preliminary check for compatibility between the account and the feature you are going to use.
• Map API responses to correspondent objects definition
• Test the operation

Example web client

let request = require("request");

let apiRequest = (endpoint, httpmethod, body, success, failure) =>
request({
  uri: `https://api.rebrandly.com/v1/${endpoint}`,
  method: httpmethod,
  body: body ? JSON.stringify(body) : null,
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY'
  }
}, (err, response, body) => {
    if (err) failure(JSON.parse(err));
    else success(JSON.parse(body));
  })
}

let getRequest = (endpoint, success, failure) => {
  return apiRequest(endpoint, "GET", null, success, failure)
}

let postRequest = (endpoint, body, success, failure) => {
  return apiRequest(endpoint, "POST", body, success, failure)
}

let getAccount = (success, failure) => {
  return getRequest("account", success, failure);
}

let createNewLink = (link, success, failure) => {
  return postRequest("links", link, success, failure);
}

exports.getAccount = getAccount;
exports.createNewLink = createNewLink;

Example application

let rebrandlyClient = require("./rebrandly.js")
let slashtag = `test-${Math.floor(Math.random()*999999)}`
//for the sake of example, slashtag should always be different
//if you do not specify one, a random (and collision-free) one will be used

let linkDef = {
  "title": "My first link",
  "slashtag": slashtag,  
  "destination": "https://www.google.com"
};

let onError = (err) => {
  console.log(JSON.stringify(err))
}

let onLinkCreated = (link) => {
  console.log(`Congratulations ${account.fullName}! You just created your first link.`)
  console.log(`Link ID is ${link.id}`)
  console.log(`Short URL is: https://${link.shortUrl}`)
  console.log(`Destination URL is: ${link.destination}`)       
}

rebrandlyClient.createNewLink(linkDef, onLinkCreated, onError);

Congratulations John! You just created your first link.
Link ID is: m5jk4cc5bjop45d6bbe97b06ac2d1ghj
Short URL is: https:// rebrand.ly/test531972
Destination URL is: https://www.google.com