<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:
- Get interaction
- 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 RESTful via HTTP requests. The various HTTP requests do take place via "our protocols".
Character set
<UIKey> uses a limited character set: 148 characters are allowed when building keys:
- 32 to 126 : 95 chars (inclusive)
- 192 to 207 : 16 chars (inclusive)
- 209 to 214 : 6 chars (inclusive)
- 216 to 246 : 31 chars (inclusive)
… 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 possibilities.
The <UIKey> protocols
As exposed before, the means to interact with <UIKey> are called "protocols". Each protocol achieves a well-defined interaction. When <UIKey> responds, it does this in two possible ways:
- html
- xml
The default response mode is 'html'. We shall see later how the return can be passed in 'xml'.
Supported protocols
- Follow:
'f'…http://uikey.org[1] ?f=<data> - Whatis:
'w'…http://uikey.org?w=<data> - Recommend:
'r'…http://uikey.org?r=<data> - Permalink:
'p'…http://uikey.org?p=<data> - Statistics:
's'…http://uikey.org?s=<data> - Account:
'a'…http://uikey.org?a=<data> - News:
'n'…http://uikey.org?n=<data> - Events:
'e'…http://uikey.org?e=<data> - Jobs:
'j'…http://uikey.org?j=<data> - Resumes / CVs:
'cv'…http://uikey.org?cv=<data> - Categories:
'cat'…http://uikey.org?cat=<data>
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.uikey.org/?f=UIKey
… where CMMI is the key to follow. It is also used with
permalinks (or short URLs, because it is the same concept <UIKey>
wise).
Alias
http://www.uikey.org/?follow=UIKey
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.uikey.org/?w=UIKey
XML return
http://www.uikey.org/?w=UIKey&mode=xml
Alias
http://www.uikey.org/?whatis=UIKey
The 'r' protocol : recommend
The 'r' protocol is used to recommend
a key. With this, users of <UIKey> can determine which keys are
popular.
http://www.uikey.org/?r=UIKey
Alias
http://www.uikey.org/?recommend=UIKey
The 'p' protocol : permalink
With the 'p' protocol you can create
permalinks or short URLs in <UIKey> database (<UIKey> handles
permalinks in exactly the same way as short URLs).
In its simplest form, only the 'p' parameter must be passed as
illustrated below:
http://www.uikey.org/?p=http://www.uikey.org
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.uikey.org/?p=http://www.uikey.org&url-success=http://www.mydomain.com/permaOK/
… and
http://www.uikey.org/?p=http://www.uikey.org&url-failure=http://www.mydomain.com/permaNOK/
Alias
http://www.uikey.org/?permalink=http://www.uikey.org
The 's' protocol : statistics
The 's' has NOT been released yet.
Announcements will be made via our tweets on Twitter.
The 'a' protocol : account
The 'a' protocol is used to confirm an
account. It is used internally by <UIKey>.
http://www.uikey.org/?a=84556bec097904ffb83f33fe8570ed2a
Alias
http://www.uikey.org/?account=84556bec097904ffb83f33fe8570ed2a
The 'n' protocol : news
The 'n' protocol has NOT been released yet.
Announcements will be made via our tweets on Twitter.
The 'e' protocol : events
The 'e' protocol has NOT been released yet.
Announcements will be made via our tweets on Twitter.
The 'j' protocol : jobs
The 'j' protocol has NOT been released yet.
Announcements will be made via our tweets on Twitter.
The 'cv' protocol : Resumes / CVs
The 'cv' protocol has NOT been released yet.
Announcements will be made via our tweets on Twitter.
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.uikey.org/?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.uikey.org/?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.uikey.org/?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.uikey.org/?cat=1;4&lang=fr&country=US&mode=xml
… this will do the same as before but will return the result in XML.
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: ?mode=xml.
Example:
http://www.uikey.org/?w=UIKey&mode=xml
This mode does NOT apply on the 'f' for
obvious reasons.
Footnotes
[1] … www.uikey.org and www.ui.tl point to exactly the same site: they are aliases.