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

http://www.ui.tl/?w=UIKey&xml
        

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

Specifications

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.

http://www.ui.tl/?a=84556bec097904ffb83f33fe8570ed2a
            
Alias
http://www.ui.tl/?account=84556bec097904ffb83f33fe8570ed2a
            
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.

http://www.ui.tl/?auth=key&pwd=my-password
            

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:

http://www.ui.tl/?c=UIKey&url-success=http://www.mydomain.com/permaOK/
            

… and

http://www.ui.tl/?c=UIKey&url-failure=http://www.mydomain.com/permaNOK/
            
XML Return
http://www.ui.tl/?c=UIKey&xml
            
Alias
http://www.ui.tl/?create=UIKey
            
Try It Yourself
http://www.ui.tl/?a={$szGUID}
http://www.ui.tl/?a={$szGUID}&xml
            

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

http://www.ui.tl/?cat=1;4
            

… will extract all keys of category 1 or 4.

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

http://www.ui.tl/?cat=1;4&lang=en;fr
            

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

http://www.ui.tl/?cat=1;4&lang=fr&country=US
            

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

http://www.ui.tl/?cat=1;4&lang=fr&country=US&xml
            

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

Try It Yourself
http://www.ui.tl/?cat=1
http://www.ui.tl/?cat=1&xml
            

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
http://www.ui.tl/?cv=CV-PAT
http://www.ui.tl/?cv=CV-PAT&xml
            

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
http://www.ui.tl/?d=INVOICE-38584e52-c62e-43ed-86c6-cf89cf3a7360
http://www.ui.tl/?d=INVOICE-38584e52-c62e-43ed-86c6-cf89cf3a7360&xml
            

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.

http://www.ui.tl/?del=123456
            

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:

http://www.ui.tl/?f=UIKey
            

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

Alias
http://www.ui.tl/?follow=UIKey
            
Try It Yourself
http://ui.tl/?f=pb
http://ui.tl/?f=pb&xml
            

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.

http://www.ui.tl/?koo=48
            
Try It Yourself
http://www.ui.tl/?koo=48
http://www.ui.tl/?koo=48&xml
            

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.

http://www.ui.tl/?o=id
            

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:

http://www.ui.tl/?p=http://www.ui.tl
            

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

http://www.ui.tl/?p=http://www.ui.tl&url-success=http://www.mydomain.com/permaOK/
            

… and

http://www.ui.tl/?p=http://www.ui.tl&url-failure=http://www.mydomain.com/permaNOK/
            
Alias
http://www.ui.tl/?permalink=http://www.ui.tl            

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
http://www.ui.tl/?qr=CALL-ME
http://www.ui.tl/?qr=SMS-ME
            

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)
            
Alias
http://www.ui.tl/?recommend=UIKey
            
Try It Yourself
http://www.ui.tl/?r=pb
http://www.ui.tl/?r=pb&xml
            

The 's' protocol : statistics

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

Try It Yourself
http://www.ui.tl/?s=pb
http://www.ui.tl/?s=pb&xml
            

The 'su' protocol : subscribe

The 'su' protocol has NOT been released yet.

Try It Yourself
http://www.ui.tl/?su=pb
            

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:

http://www.ui.tl/?t=http://www.1ls.be/media/final-final-item-card-1.png
            
XML return
http://www.ui.tl/?t=http://www.1ls.be/media/final-final-item-card-1.png&xml
            
Alias
http://www.ui.tl/?target=http://www.1ls.be/media/final-final-item-card-1.png
            
Try It Yourself
http://www.ui.tl/?t=http://www.1ls.be/media/final-final-item-card-1.png
            

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:

http://www.ui.tl/?w=UIKey
            
XML return
http://www.ui.tl/?w=UIKey&xml
            
Alias
http://www.ui.tl/?whatis=UIKey
            
Try It Yourself
http://www.ui.tl/?w=pb
http://www.ui.tl/?w=pb&xml
            

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

http://www.ui.tl/?whoami
            

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

XML return
http://www.ui.tl/?whoami&xml
            
Try It Yourself
http://www.ui.tl/?whoami
            

Categories

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.

Footnotes

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