<UIKey> Application Programming Interface

Building Blocks

You can build your web site with the same technologies we use. The entire <UIKey> experience is built on an Open Source web framework (PHP): Vae Soli!.

Vae Soli! contains a number of predefined widgets to interact with <UIKey>: a registration form, a search form, a permalink creation form, etc.

Getting Started

Our Application Programming Interface permits two types of interaction:

  1. Get interaction
  2. Set interaction

With the Get interactions, you, as a developer, you can retrieve information from <UIKey> databases.

With the Set interactions you can set information into <UIKey> databases: add, update and delete.

The interactions with <UIKey> adhere to the principles of web services going over HTTP. The various HTTP requests do take place via our list of protocols.

Character set

<UIKey> uses a limited character set: 148 characters are allowed when building keys:

… which translates to the following character set (it starts with a blank): !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_` abcdefghijklmnopqrstuvwxyz{|}~

As the key length can go up to 120 characters, there are 2.700261643301888696052576509549e+260 unique possibilities in <UIKey>.

The <UIKey> Domains

<UIKey> is available on two domains that are considered as aliases of each other and can be used interchangeably : uikey.org and ui.tl. The latter is a handy shortening.

The <UIKey> Protocols

As exposed before, the means to interact with <UIKey> are called "protocols". Each protocol achieves a well-defined and pretty limited interaction. When <UIKey> responds, it does this in two possible ways:

  1. html (default)
  2. xml

The default response mode is html as indicated above. <UIKey> protocols are used via simple web services as exposed here below.

Supported Protocols

  1. Account: 'a'http://www.ui.tl?a=<data>[1]
  2. Authentication: 'auth'http://www.ui.tl?auth=<data>
  3. Create: 'c'http://www.ui.tl?a=<data>
  4. Categories: 'cat'http://www.ui.tl?cat=<data>
  5. Resumes / CVs: 'cv'http://www.ui.tl?cv=<data>
  6. Document: 'd'http://www.ui.tl?d=<data>
  7. Delete: 'del'http://www.ui.tl?del=<data>
  8. Edit: 'edit'http://www.ui.tl?edit=<data>
  9. Events: 'ev'http://www.ui.tl?ev=<data>
  10. Follow: 'f'http://www.ui.tl?f=<data>
  11. Jobs: 'j'http://www.ui.tl?j=<data>
  12. Keys of Owner: 'koo'http://www.ui.tl?koo=<data>
  13. News: 'n'http://www.ui.tl?n=<data>
  14. Owner: 'o'http://www.ui.tl?o=<data>
  15. Permalink: 'p'http://www.ui.tl?p=<data>
  16. QR-Code: 'qr'http://www.ui.tl?qr=<data>
  17. Recommend: 'r'http://www.ui.tl?r=<data>
  18. Statistics: 's'http://www.ui.tl?s=<data>
  19. Subscribe: 'su'http://www.ui.tl?su=<data>
  20. Target: 't'http://www.ui.tl?t=<data>
  21. Whatis: 'w'http://www.ui.tl?w=<data>
  22. Who Am I: 'whoami'http://www.ui.tl?whoami

Return Methods

<UIKey> provides 2 return types: html (default) or xml.

In order to obtain the response in xml, simply include an additional parameter in your request: ?xml. Example:


This xml mode does NOT apply on the 'f' protocol for obvious reasons.


The 'a' protocol : account

The 'a' protocol is used to confirm an account. It is used by <UIKey> to activate an account that has been created by the registration page or via the 'su' protocol.

Try It Yourself
http://www.ui.tl/?a=Patrick Boens
http://www.ui.tl/?a=Patrick Boens&xml

The 'auth' protocol : authentication

The 'auth' protocol is used to provide universal authentication services. It is used internally by <UIKey> and by many sites built with Vae Soli!

Many authentication services rely on a simple pair of a User Account + Password. This is the very nature of <UIKey>: a target URL is associated to a key. Therefore, <UIKey> can serve as a generic authentication service.

When passwords are submitted to <UIKey>, they are NEVER stored as raw material. Instead, they're transformed and hashed in such a way that even <UIKey>'s personnel NEVER knows any password. This is what makes <UIKey> an ideal generic authentication service.


The 'c' protocol : create

The 'c' protocol is used to create a key in the <UIKey> databases programmatically.

The creation of a key can be successful or can fail. You can indicate where UIKey must branch the execution in case of failure or even in case of success:


… and

XML Return
Try It Yourself

The 'cat' protocol : categories

The 'cat' protocol allows you to retrieve keys of a given category, a given language, a given country. Multiple categories can be extracted in one run with a tokenized string of categories (';' is the separator):


… will extract all keys of category 1 or 4.

If you use more parameters, like lang and/or country, you will narrow the selection.


… will extract all keys of category 1 or 4 and whose language is either 'en' or 'fr'.


… will extract all keys of category 1 or 4 and whose language is 'fr' (French) and whose country context is set to 'US' (United States).


… this will do the same as before but will return the result in XML.

Try It Yourself

The 'cv' protocol : resumes / CVs

The 'cv' protocol has NOT been released yet. Announcements will be made via our tweets on Twitter.

Try It Yourself

The 'd' protocol : document

This protocol is not ready yet. Many other protocols are actually specialized and more specific 'document' protocols: 'news', 'events', 'jobs', …

Try It Yourself

The 'del' protocol : delete

This protocol can be used by the owner of a key to remove the key from the <UIKey> registry.

Once a key has been removed from the registry there is NO way to restore it: that's what is meant by physically and permanently removed.


As stated before, only the owner of a key can delete it!

The 'edit' protocol : edit/modify

This protocol can be used by the owner of a key to change few of its properties:

  • Description
  • TTL
  • Target
  • Associated email address
  • Categories
  • http://www.ui.tl/?ed=public&desc=Here enter a valuable description&target=http://www.mydomain.com/res/

The 'ev' protocol : events

The 'ev' protocol has NOT been released yet. Announcements will be made via our tweets on Twitter.

The 'f' protocol : follow

The 'f' protocol is used to redirect the user to the target URL. You know a given key exists in <UIKey> databases and you simply want to redirect the user to the final destination: you follow the target URL. Example:


… where UIKey is the key to follow. The 'f' protocol works with any key that is associated to a URL.

Try It Yourself

The 'j' protocol : jobs

The 'j' protocol has NOT been released yet. Announcements will be made via our tweets on Twitter.

The 'koo' protocol : keys of owner

The 'koo' protocol is there to see what keys have been registered by a given owner.

The parameter that is expected in this protocol is not a key as one may expect: it is rather the 'id' of the owner that is used. If one needs to gain more information about the owner of a key, then it is possible to use the 'o' protocol.

Try It Yourself

The 'n' protocol : news

The 'n' protocol has NOT been released yet. Announcements will be made via our tweets on Twitter.

The 'o' protocol : owner

The 'o' protocol is used to provide information about the owner of a key.


The 'p' protocol : permalink

<UIKey>'s permalink shortens any URL. You can let <UIKey> create the key for you or you can try to force the key thanks to a prefix (if you're bit lucky though!). If the prefix already exists, <UIKey> will create an automatic key instead. Are you lucky today?

With the 'p' protocol you can create permalinks (also called short URLs) in <UIKey> databases.

In its simplest form, only the 'p' parameter must be passed as illustrated below:


In that case, <UIKey> responds in html. But … you can also inform <UIKey> where it needs to go in case of success or failure.


… and


The 'qr' protocol : qr-code

The 'qr' protocol makes it easy to create QR-Codes in <UIKey>. This protocol is actually used internally by <UIKey> for example in the 'w' protocol.

However, this protocol is not fully documented yet as we work on it for the time being to include support for direct phone calls, short messages (SMS), geo scheme and mail.

Try It Yourself

The 'r' protocol : recommend

The 'r' protocol is used to recommend a key. With this, users of <UIKey> can determine which keys are popular for them.

It is all possible to condemn a key/target URL with the same protocol. Example : "http://www.uikey.org/?r=UIKey&no".

http://www.ui.tl/?r=UIKey // Recommend (counter is incremented)
http://www.ui.tl/?r=UIKey&no // Do not recomment (counter is decremented)
Try It Yourself

The 's' protocol : statistics

The 's' has NOT been released yet. Announcements will be made via our tweets on Twitter.

Try It Yourself

The 'su' protocol : subscribe

The 'su' protocol has NOT been released yet.

Try It Yourself

The 't' protocol : target

The 't' protocol is the reverse of the 'w' protocol protocol of <UIKey> : given a target URI it will return the associated key. Example:

XML return
Try It Yourself

The 'w' protocol : whatis

The 'w' protocol is the most widely spread protocol of <UIKey>. It gives the details of a key. Whatis this key? Example:

XML return
Try It Yourself

The 'whoami' protocol : who am I

The 'whoami' protocol can be used when the visitor has signed in. In such case it makes it easy to remember with which identity the visitor operates on <UIKey>.


The protocol does not expect any parameter: the current user identity is assumed.

XML return
Try It Yourself


Keys can be associated to one or multiple categories. The categories used by <UIKey> are NOT fixed yet: so far, they're a combination of NACE, NAF, MCC codes and object types.

At the moment these categories become FINAL they will be commmunicated to the public.


[1] … www.uikey.org and www.ui.tl point to exactly the same site: they are aliases.