.NET DLL

The DLL was written under Microsoft .NET v2.0.50727. If you find you need a version of the library in another .NET version, please let us know. Currently the use of the DLL has been tested with Windows 2000 (32-bit), XP (32-bit), Vista (32-bit and 64-bit) and should be compatible with Windows 7.

The DLL has not yet been tested with Windows Mobile or Windows Phone 7. It was not designed with compact framework in mind. In the near future we will have an official answer on this subject or we will create a CF version. We previously had a Windows Mobile app with the older version of the API. We intend to update the application, so one way or another we will have an “official” answer on this subject.

In order to use the shortner API you will need a developer key and a user login. You can obtain both by registering as a user with shortner. Since shortner is a platform, the user account will work across all shortner sites. Once you are a registered user, login and go to your profile page and than to the API-key page and request a new API key.

Now that you have the your API key we can get started. You can obtain the library, here. Extract the DLL from the ZIP file, to a place where you intend to keep the file; as we will need to refer to it's path in Visual Studio.

Assuming you have created a project in Visual Studio (2005, 2008 or higher), at the project level, add reference to the DLL (add reference, browse…). Once that is complete, you will need to add reference to the shortner class (before your main class).

Imports shortner.shortnerClass

using shortner.shortnerClass;

Now that you have added your references (to the project and to your form class), let's discuss some expectations, as well as some of the behaviors in regards to the API. When you're creating a new shornter URL, the library will check the syntax of the URL. Only ”ftp://”, ”http://”, and ”https://” is valid. In this version of the library (v1.0.0.0), you cannot specify any other shortner links or shortner sites. In other words you cannot shortner “mailto:shortner@isthegreatest.com” and/or “http://shortner.com/1234”. In addition to this, the API checks against a list of malware sites/links and will not allow for link creation for malware sites.

I'm a big fan of ArrayLists and the library makes use of this data-type. My recommendation would be to set 2 global values for the sessionID return that will come from validating/logging-in a user, and the list of available shortner services. I will expand on this subject later (see the bottom of the page).

In the slim chance you have never used an ArrayList before, here's an example of how to substantiate this data-type:

VB.net

  Dim myArrayList As New ArrayList

C#

  {
      ArrayList myArrayList = new ArrayList();
  }

This function currently serves no purpose, just ignore.

Returns the MD5 hash of str

input

return

The ShortnerURL function passes through to this function, it's not required you pre-validate your link, but it's directly available in case you want to check a url before submission. As mentioned above the only acceptable url inputs must prepend with ”ftp://”, ”http://”, or ”https://” and cannot include another shortner site as part of it's url.

input

return

Any function that requires apiKey passes through to this function, it's not required for anything you would directly need. It properly formats rest-url that will be called for the API methods.

input

return

Returns the session-id of the user. The session-id returned is valid across all shortner sites; but is generated based on the requesting IP address for the user. So if a user is “logged into multiple shortner sites” only the most recent session-id is valid.

input

return

Use this function to validate a session-id.

input

return

Use this function to “logout” (clear out) a session-id in the system.

input

return

Use this function to create the “shortner” link. For services, provide what's returned from GetServices. If you're application is only going create links from one shortner site, than substantiate a new ArrayList object and add just the one shortner domain; example: “qrk.me”, “oglink.com”. Keep in mind the API knows which shortner sites are available. So if you try to spoof this value the API will know and will refuse the link creation.

input

return

Returns an ArrayList of the currently available “shortner sites” to your API key. Not all shortner sites are public. Hosted shortner sites can be private to only certain API keys.

input

return

Session ID Once you “login” a user, I would recommend caching that users session-id. The session-id remains valid until it's been signed out, or replaced by a new session request. Keep in mind the session-id is seeded by the requesting IP. So, if more then one IP-source requests a session-id for a user, only the last successful request will be valid.

Services and Domains After you “login” and receive a user session-id, I recommend caching the GetServices return. This way you can refer to the cached value(s) instead of having to get the service list each time you want to create a new shortner link. The values in the returned arraylist are the shortner domain sites that are accessible to your API key (“shortner.com”, “qrk.me”, “oglink.com”, etc).

While coding your application, we recommend you use “shortner.org” as your domain value. We clear out the “shortner.org” database every night. We prefer you to not create “test links” with the non-dev shortner sites.

If you have any questions, concerns, etc pleae feel free to contact me, at: alan (at) shortner.com