.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.

Things to Know (read first)

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.

Version (history)

Add References (step 1)

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).

VB.net

Imports shortner.shortnerClass

C#

using shortner.shortnerClass;

Using the shortner.shortnerClass (step 2)

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.

Recommendations

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).

Using an ArrayList

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();
  }

The Functions

CreateBoundary()

This function currently serves no purpose, just ignore.

MD5HashStr(str)

Returns the MD5 hash of str

input

NameTypeValue
str string input user password

return

TypeValue
string MD5 hash (of str)

validateURLformat(urlStr, services)

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

NameTypeValue
urlStr string the url that will be “shortner'd”
services arraylist this should be an arraylist of values returned from GetServices

return

TypeValue
boolean (true/false)

RestURL(apiKey, domain, method)

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

NameTypeValue
apiKey string your API key that was provided for your development efforts
domain string this should be the name of the shortner site you're submitting your activity to; example: shortner.com, shortner.org, qrk.me, oglink.com
method string the API method you're calling

return

TypeValue
string the rest-url that will be call that combines the shortner site, API key and API method

GetSessionID(apiKey, username, passwordHash, domain)

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

NameTypeValue
apiKey string your API key
username string the shortner user account
passwordHash string the hash value of the user password; use the return value of MD5HashStr(<user-pass>) with the user password as input
domain string shortner site; example: shortner.com, shortner.org, qrk.me, oglink.com

return

TypeValue
string the user session-id

CheckSessionID(apiKey, sessionID, domain)

Use this function to validate a session-id.

input

NameTypeValue
apiKey string your API key
sessionID string the user session-id you wish to validate
domain string shortner site; example: shortner.com, shortner.org, qrk.me, oglink.com

return

TypeValue
boolean (true/false)

SignOutSessionID(apiKey, sessionID, domain)

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

input

NameTypeValue
apiKey string your API key
sessionID string the user session-id you wish to logout
domain string shortner site; example: shortner.com, shortner.org, qrk.me, oglink.com

return

TypeValue
boolean (true/false)

ShortnerURL(apiKey, services, sessionID, domain, url, nsfw, password, tags)

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

NameTypeValue
apiKey string your API key
services arraylist this should be an arraylist of values returned from GetServices
sessionID string the user session-id you wish to validate
domain string shortner site; example: shortner.com, shortner.org, qrk.me, oglink.com
url string the link you wish to “shortner”
nsfw boolean if the link you are creating is Not Safe For Work; set this to True
password string provide the link password here; for no password leave the value empty (2 double quotes)
tags string provide the tags, for the link here (comma delimited); for no tags leave the value empty (2 double quotes)
description string provide a description for your link; for no description leave the value empty (2 double quotes)
recycle boolean (true / false) if set as true, the API will return the existing link (if no link previously existed a new link will return). if set to false it will create a new link
test boolean (true / false) if set as true, the API will return a dummy link. if set to false it will return a real link

return

TypeValue
string the shortner url/link

GetServices(apiKey)

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

NameTypeValue
apiKey string your API key

return

TypeValue
arraylist current “shortner sites” available to your API key

Recommendations

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).

Testing

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.

Contact

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

 
example/dotnetdll.txt · Last modified: 2011/10/15 19:11 (external edit)
 
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki