Shortened URL Service

Lead(s): Former user (Deleted)

Description: The Shortened URL service for Sakai is a simple service that allows tools and services to shorten links to anything, either via the Java service, or via the Entity Provider.

Institutions can choose how they want the shortened URLs to appear via a setting in sakai.properties - ranging from the built in URL shortener which returns URLs like http://sakai.edu.au/x/1sF5cD, to an implementation that uses the bit.ly URL shortening service: the choice is up to you.

This service is available in Sakai 2.8 and onwards or you can grab it from:
from SVN: https://source.sakaiproject.org/svn/shortenedurl
or as a binary: https://source.sakaiproject.org/maven2/org/sakaiproject/shortenedurl/

For institutions

By default, the URL shortener returns the original URL unchanged. So in order to start seeing shorter URLs, you need to configure it in sakai.properties. You can choose an implementation from the available list below. Note that the bit.ly implementation requires extra configuration (documented below):

## RANDOMISED
# Uncomment this to use the built in URL randomiser/shortener (recommended)
#shortenedurl.implementation=org.sakaiproject.shortenedurl.api.RandomisedUrlService

## BIT.LY
# Uncomment this to use the bit.ly URL shortner
#shortenedurl.implementation=org.sakaiproject.shortenedurl.api.BitlyUrlService

# You must also have a bitly account. So signup, navigate to http://bit.ly/a/your_api_key, retrieve your details, uncomment and set the following:
#shortenedurl.implementation.bitly.login=johnsmith
#shortenedurl.implementation.bitly.key=123qwe456asd789zxc

You can also create your own implementation very easily, see the section Creating your own implementation.

Lastly, by default, the service does not allow you to shorten URLS to anything outside of the Sakai installation using the /direct/url/shorten entity provider. If you need this, and you understand the implications, you can set the following property to true:

shortenedurl.external.enabled=false

Supported tools

Resources (SAK-21848) 2.10 onwards. Easily back ported. Activate via:
```
shortenedurl.resources.enabled=true
```

Portal (SAK-21865). 2.10 onwards. Displays a permalink to the tool, can also be shortened, or left as the full URL. Configuration:

# enables a link icon for each tool in the portal so you can get a direct URL to the tool.
portal.tool.direct.url.enabled=false

# in conjunction with the above, if set to true, shows the option to shorten that link.
shortenedurl.portal.tool.enabled=true

For developers

There are two ways to use the service in your app, via Spring injection, or via AJAX.

Spring injection

Inject the following API into your application via your Spring wiring, javax.annotation.Resource or use the Sakai ComponentManager:

org.sakaiproject.shortenedurl.api.ShortenedUrlService

Now call the shorten(String url) method to shorten the given URL, eg:

String shortUrl = shortenedUrlService.shorten("http://sakaiproject.org");

Assuming the RandomisedUrlService is configured, this will produce something like the following:

http://your.sakai.server/x/1sF5cD

If you want a more 'secure' URL, use the alternate method to produce a much longer URL (22 chars), shorten(String url, boolean secure), where secure is true.

Assuming the RandomisedUrlService is configured, this will produce something like the following:

http://your.sakai.server/x/1sF5cDcv0ghHksoRss45jkaa

Note that this 'secure' method is only implemented in the RandomisedUrlService implementation.

AJAX

Make a GET request to the following URL:

/direct/url/shorten?path=URL

Note that the URL must be URL encoded. You can also use the 'secure' mode of the RandomisedUrlService by adding the secure URL parameter, e.g:

/direct/url/shorten?path=URL&secure=true

Creating your own implementation

This is extremely easy. All you need to do is implement a single interface:

org.sakaiproject.shortenedurl.api.ShortenedUrlService

At a minimum you should flesh out the shorten(String url) method. You can optionally flesh out the shorten(String url, boolean secure) method if required, otherwise just pass the control back to the first method, ignoring the second parameter.

Then, add some Spring wiring to register it:

<bean id="org.sakaiproject.shortenedurl.api.YOUR_API_NAME"
    	class="org.sakaiproject.shortenedurl.impl.YOUR_CLASS_NAME"
    	singleton="true"
    	init-method="init">
    	<!-- ANY PROPERTIES OR OTHER API'S HERE -->
</bean>

And finally, in sakai.properties, set your new implementation to be the one used preferentially:

shortenedurl.implementation=org.sakaiproject.shortenedurl.api.YOUR_API_NAME

When you restart Sakai, it will be registered as the default and all URL shortening will go through your new implementation. In addition, the EntityProvider will be automatically configured to pick it up, so you can test it straight away in your browser. See the section AJAX.

Project: Shortenedurl