Migrating from Google URL Shortener API

Authenticating

Google URL Shortener API supports OAuth 2.0 and API keys as authentication methods, empowering (almost) every Google Account with the ability to shorten its own URLs with the goo.gl domain.
In the Rebrandly API, developers are provided with the same two methods too, each meant to fit a specific set of use-cases:

• You can create an API Key for your Rebrandly account. This is, by far, the easiest way to approach our API. If you were using Google URL Shortener for your own account only, this is likely to be the best possible choice.

• If your application is designed to allow third-parties - including yourself - to use their own Rebrandly account to shorten URLs, you can contact us to create an OAuth application for you.

Workspaces and Domains

Unlike Google URL Shortener, in Rebrandly you can choose your [custom domain name](doc:branded-domain-mo del) to brand your links. Also, in order to better organize your link collection, you need to define Workspaces in your account, which you can think of as collaborative folders you can invite your colleagues to in order to create, share and manage branded links as a team.

When you subscribe to a FREE plan, we prepare a main Workspace for you to start using, and when you register or configure a new domain name, you can also decide in which Workspaces you want to include it in to create new branded links. You can change the organization of your account any time by adding, editing and deleting Workspaces, as their main goal is to provide you with team and domain management.

Be sure that your domain has been shared into the Workspace you plan to use, and that your application - when operating with Branded Links - will always explicit which Workspace and which particular Domain has to be used.
We recommend that you do not rely on our API defaulting logics, as they might not match your expectations over time, i.e. when your account will become multi-workspace and multi-domain.

## Link management

If you have an account, a workspace, and a domain, you are all set to create your first branded link.
In Google URL Shortener's API, you used to perform an HTTP POST API call to define a link:

POST https://www.googleapis.com/urlshortener/v1/url?key=YOUR_API_KEY
Content-Type: application/json

{"longUrl": "http://www.google.com/"}

Well, it is not that different in the Rebrandly API. We call destination what Google used to call the longUrl:

POST https://api.rebrandly.com/v1/links
Content-Type: application/json
apikey: YOUR_API_KEY

{"destination": "http://www.rebrandly.com/"}

The example is simplistic, as this call would produce a link using your default Workspace and the rebrand.ly domain. The below call would create a link with a specific Workspace, a specific Domain, and with a custom slashtag (which was not available in Google URL Shortener):

POST https://api.rebrandly.com/v1/links
Content-Type: application/json
apikey: YOUR_API_KEY
workspace: YOUR_WORKSPACE_ID

{"destination": "https://www.rebrandly.com/", "domain": { "fullName": "your-branded-domain.com" }, "slashtag": "cool" }

Please refer to Creating a new link section for more info.
An example response for the link creation request will look like:

{
   "id": "d33g3495f2944be0b55aca5c5c7e0a29",
   "destination": "https://www.rebrandly.com/",
   "domain": {
     "id": "f34ca8927b67425fa1d8fc22c468823f",
     "fullName": "your-branded-domain.com"
    },
   "slashtag": "cool",
   "shortUrl": "your-branded-domain.com/rbgi304d"
}

Whereas in Google URL Shortener your answer would have been this:

{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/fbsS",
 "longUrl": "https://www.rebrandly.com/",
 "status": "OK"
}

In Rebrandly, we call shortUrl what Google used to call just id. We refer to the shortUrl, more generally, as the concatenation between your branded domain and the slashtag, which is the slug part after /.

🚧

Beware false friends

In Rebrandly, the id property - like in all other API resources it manages - is used to uniquely identify the link across all others. By contrast, Google URL Shortener refers to the short link itself (including the http:// protocol) with the name id.

📘

About HTTPS

In Rebrandly, we support SSL encryption everywhere. You can safely share your links with https:// protocol, by pre-pending it to the value you get from API in the shortUrl property. You might have - in your scripts - some rewriting rule which was replacing http:// with https:// (as goo.gl do support https, of course): in Rebrandly, you are going to concatenate https:// with the value of shortUrl property, instead.

If your application also performs advanced link management, you can refer to our link management section for additional information

Unlike Google URL Shortener API, in Rebrandly you can edit and even delete a specific link, as well as tagging and attaching retargeting scripts to it.

Analytics

It is possible to gather info about the number of clicks that happened on a given branded link, like you were used to doing through Google URL Shortener API. Beside each link resource, Rebrandly discloses info about click traffic (see clicks and lastClickAt properties in Branded short links model).