@datafire/shorten_rest

Client library for Shorten.REST API Documentation

Installation and Usage

npm install --save @datafire/shorten_rest

let shorten_rest = require('@datafire/shorten_rest').create({
  ApiKeyAuth: ""
});

.then(data => {
  console.log(data);
});

Description

Introduction

The Shorten.rest API allows you to programmatically create short URLs (an 'alias') for longer URL (a 'destination').

Each alias you create can be used to redirect the end user (person clicking on the link) to one or more destination URLs

A default destination is always set and specific destinations can be set to redirect the end user to preferred destinations based on the user's geographical location (country) and device Operating System.

In order to use the Shorten.Rest URL Shortening API you can choose to bind your own branded domain, sub-domain or to use our default domain - Short.FYI

Destination Matching

When creating or editing a short URL ('alias') you can choose to specify a destination for each country and OS (Supported OSes list) combination.

When a user clicks on the short link, Shorten.rest will examine the end user's country (determined by User's IP) and OS (User agent) and match the most suitable destination for each user.

(*) If no destination is set for a specific request combination Shorten.rest will use the default destination that exists within each short URL

(**) BRANDED DOMAINS: If the requested alias does not exist in our database - Shorten.rest will redirect the user to the default fallback you set within your dashboard under the ‘Alias Not Found Page Url’ value for a custom domain.

(***) Operating System (OS) destinations are stronger than a country destination! For example - if you have a custom landing page that is targeting people in the USA and a second landing page that is hyper focused for people who use iOS devices - a person clicking on your link in the USA that is on an iPhone will be redirected to the iOS landing page, while all other devices will be redirected to the USA landing page.

| OS | Country | Destination | | :------------: |:---------------:| -----| | iOS | | YourDestination.com/ios | | | US | YourDestination.com/usa |

Shorten.rest will choose the YourDestination.com/ios url as the most suitable destination.

Branded Domain Attributes

When setting up your custom domain you can include optional metatags and snippets (Supported snippets list). These parameters (such as retargeting, tracking and conversion pixels) are populated and fired on click - at the time of the redirect.

By default the parameters you set in the domain setting will be included in all Short URLs associated with that domain.

You can always override the domain defaults for each URL by passing the appropriate variables when creating or updating a short URL

Setting a Custom string for an Alias (short.fyi/alias)

While creating a short URL you can specify which domain to use. You can choose to use your own branded domain or our default domain - Short.fyi.

Each Alias is unique within a domain they are related to. This means that if multiple accounts use you the same domain (for example short.fyi), if an alias is already taken you may not create a new destination for it.

That said - If you would like to use a specific alias which is already taken - the only way to do so is to create it on a new domain you own and have attached to your Shorten.rest account.

Random Aliases

By default - unless you specify a vanity URI for your alias each URL that is shortened on our platform will have a random string generated by the API. This means that if the 'alias' attribute of a /aliases POST request is not provided, or is an empty string, a random string of seven characters will be generated and returned as part of the POST response.

You can also place the @rnd macro within the alias field when you create a new alias, for example /vanity/@rnd, which might return an alias like /vanity/ZMAefRt, or /vanity@rnd, which might produce something like /vanityMRtvxadf. Only the first @rnd in an alias attribute will be replaced.

NOTES

( * ) All methods of the Shorten.REST API require that your API key be provided in x-api-key header.

(**) All API parameters are case sensitive

Actions

DeleteAlias

Deletes a single alias by providing alias and domain. If no domain is provided the API will search for the matching alias within the Short.fyi domain

shorten_rest.DeleteAlias({
  "aliasName": ""
}, context)

Input

• input object
  • domainName string: domain which alias belongs to (string without http/https or /)
  • aliasName required string: alias (without / at the beginning)

Output

Output schema unknown

GetAlias

Get detailed information for a single alias by providing its alias and domain name

shorten_rest.GetAlias({
  "aliasName": ""
}, context)

Input

• input object
  • domainName string: domain which alias belongs to (string without http/https or /)
  • aliasName required string: alias value (without / at the beginning)

Output

• output AliasModel

CreateAlias

This POST method creates a new alias under a specified domain. If no domain is specified in the request the alias will be attached to the default domain Short.fyi

NOTE: You can override the domain level Meta Tags and Tracking Snippets by specifying them for each URL. Any variables you add to a specific URL will always override domain level settings.

shorten_rest.CreateAlias({
  "body": {}
}, context)

Input

• input object
  • domainName string: domain which alias will belong to (string without http/https or /)
  • aliasName string: alias (without / at the beginning)
  • body required CreateAliasModel

Output

• output CreateAliasResponseModel

UpdateAlias

Update a single short URL by providing its alias and domain as a parameter, and the data you wish to update in the body of the request. If no domain is provided you will receive the alias found attached to the Short.fyi domain (if it exists and is linked to your account!)

NOTE:

( * )If you add a metatag or a snippet with a same name to an alias and the domain it's related to, the value will be taken from the alias and not the domain

( ** ) When you update any array property (like destinations) the block is updated completely so you have to specify the old records to avoid deleting them

( *** ) The method updates only the specified properties so if there was no change in one of them you don't have to send it.

shorten_rest.UpdateAlias({
  "aliasName": "",
  "body": {}
}, context)

Input

• input object
  • domainName string: domain which alias belongs to (string without http/https or /)
  • aliasName required string: alias (without / at the beginning)
  • body required CreateAliasModel

Output

Output schema unknown

GetAliases

Obtain a list of all alias names associated with your account and given domain. Result array is in descending order by creation date.

If no domain is specified you will receive a list of all the alias names you have created using the Short.fyi domain.

If there are more results than the limit for the request the response will return you a value in lastId property you can specify it in the continueFrom query parameter to get the next batch of records.

shorten_rest.GetAliases({}, context)

Input

• input object
  • domainName string: The domain name to get the aliases for (string without http/https or /)
  • continueFrom string: An ID returned by a previous query to continue aliases retrieval (see lastId in response)
  • limit integer: Number of results to return per request

Output

• output GetAliasesModel

GetClicks

Retrieve the raw click data for your account. Clicks are retrieved by creation date in descending order.

If there are more results than the limit for the request the response will return you a value in lastId property you can specify it in the continueFrom query parameter to get the next batch of records.

shorten_rest.GetClicks({}, context)

Input

• input object
  • continueFrom string: An ID returned by a previous query to continue clicks retrieval (see lastId in response)
  • limit integer: Number of results to return per request

Output

• output GetClicksModel

Definitions

AliasModel

• AliasModel object
  • createdAt integer
  • destinations array
    • items DestinationModel
  • domainName string
  • metatags array
    • items MetaTagModel
  • name required string
  • snippets array
    • items SnippetModel
  • updatedAt integer

ClickModel

• ClickModel object
  • alias string
  • aliasId string
  • browser string
  • country string
  • createdAt integer
  • destination string
  • domain string
  • os string
  • referrer string
  • userAgent string

CreateAliasModel

• CreateAliasModel object
  • destinations array
    • items DestinationModel
  • metatags array
    • items MetaTagModel
  • snippets array
    • items SnippetModel

CreateAliasResponseModel

• CreateAliasResponseModel object
  • aliasName string
  • domainName string
  • shortUrl string

DestinationModel

• DestinationModel object
  • country string: ISO alpha-2 country code
  • os string: Please check the supported OS list
  • url required string

GetAliasModel

• GetAliasModel object
  • createdAt integer
  • domainName string
  • name string
  • updatedAt integer

GetAliasesModel

• GetAliasesModel object
  • aliases array
    • items string
  • lastId string

GetClicksModel

• GetClicksModel object
  • clicks array
    • items ClickModel
  • lastId string

MetaTagModel

• MetaTagModel object
  • content required string
  • name required string

SnippetModel

• SnippetModel object
  • parameters object
  • id required string: Please check the supported snippets list