1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/**
\mainpage OpenLink Data Spaces
ODS, the OpenLink Data Spaces, your Web personal 3.0 cloud system provides a full-featured HTTP API. This API allows
to control almost each aspect of ODS.
\section ods_quickstart Quickstart
This quickstart into the ODS API is meant to allow the client developer to quickly create new accounts, log users into
the system and change aspects of the user profiles.
ODS supports several ways of creating new user accounts, the most basic being user.register() which creates new accounts
through classical user credentials. In addition to that user.authenticate.browserid() and user.authenticate.webid() allow
to create new accounts by authorizing via a BrowserID or WebID respectively. Last but not least user.authenticate.authenticationUrl()
allows to create new user accounts by authenticating via third-party services like Facebook or Google through OAuth.
Once a user account has been created users can either authenticate single method calls via \ref ods_authentication_password_hash or
WebID or they can create new user sessions which can be used to authenticate an arbitrary number of calls. User sessions are
created in one of several ways: user.authenticate() provides classical password digest authentication and is, thus, the counterpart
to user.register(). The multi-purpose methods user.authenticate.webid(), user.authenticate.browserid(), and user.authenticate.authenticationUrl()
allow to create new user sessions via WebID, BrowserID, or third-party service authentication.
Successful creation of a new user account or authentication with one of the methods described above results in a new
user session which looks as follows:
\verbatim
<userSession>
<sid>1de236f5da2f32d92e8c0cce5053a96e</sid>
<user>
<uname>demo</uname>
<uid>127</uid>
<new>0</new>
<dba>0</dba>
</user>
</userSession>
\endverbatim
For more details see the respective method documentation.
\section ods_overview Overview
ODS consists of the core framework and several apps. This API documentation is structured in a similar fashion.
\b Framework \b Modules
- \ref ods_module_user
- \ref ods_module_ontology
- \ref ods_module_instance
\b ODS \b Applications
- \ref ods_module_calendar
- \ref ods_module_addressbook
- \ref ods_module_bookmark
- \ref ods_module_feeds
- \ref ods_module_discussion
- \ref ods_module_briefcase
- \ref ods_module_weblog
\section ods_access_point ODS Access Point
The API described here can be accessed via the ODS HTTP API endpoint like \p http://host:port/ods/api/METHOD. (Examples are
provided in the documentation of the specific methods.) Parameters specific to each
method are given as URL parameters if using an \em HTTP \em GET, as www-url-encoded or multipart/form-data if using an \em HTTP \em POST.
Many methods come with examples to make it easier to get started.
*/
/**
\page ods_authentication ODS Authentication
Most API calls which modify data, i.e., CRUD operations, need authentication; thus
the requests need to be authenticated using OAuth, or session + password hashes. The
user account used to authenticate in either case MUST have relevant privileges to a given
ODS data space. This is done by granting owner or author level membership to the given data space.
\section ods_authentication_password_hash Password Hash Authentication
When authenticating via password hashes parameters \p user_name and \p password_hash need to be specified. The
password hash uses the \em sha1 digest algorithm and includes both the user name and the password.
\subsection ods_authentication_password_hash_examples Password Hash Authentication Example
To authenticate user \p demo with password \p foobar the sha1 digest of the term \p demofoobar needs to be provided.
This can be created via openssl or any sha1 tool:
\code
# echo -n "demofoobar" | openssl dgst -sha1
# echo -n "demofoobar" | sha1sum
\endcode
\section ods_authentication_session_id Authentication via Session Id
The typical authentication method for a UI client is to create an ODS session via user.authenticate(). Several methods
are supported, among them password hash as explained above or OAuth. A session created via user.authenticate() is identified
by its session id. This session id can then be used to authenticate in any method call by providing two parameters:
- \p sid This is the session id returned by user.authenticate().
- \p realm The realm needs to be set to \p wa. ("wa" is the former name of ODS which is still used to identify it internally
to the Viruoso server.)
\b Tip: user.info() can be used to get details about the user account accociated to a session ID. This is very useful when
reusing a session id which has been stored in a cookie or something similar.
\subsection ods_authentication_session_id_example Session Id Authentication Example
If the session id created via user.authenticate() is for example \p 1de236f5da2f32d92e8c0cce5053a96e a call to calendar.get()
could be authorized as follows:
\verbatim
http://demo.openlinksw.com/ods/api/calendar.get?sid=1de236f5da2f32d92e8c0cce5053a96e&realm=wa&event_id=102
\endverbatim
\section ods_authentication_oauth OAuth Support in ODS
This section describes the OAuth client support in ODS which allows users to log into ODS through their third-party service
credentials. ODS abstracts the whole process and, thus, acts as an OAuth proxy giving clients access to a wide variety of
services through the same API.
\subsection ods_authentication_oauth_precon OAuth Preconditions
ODS supports authentication through the OAuth API of services like Twitter or LinkedIn. In order for this to work ODS requires corresponding
OAuth consumer keys (or client app IDs) which need to be stored in ODS through admin.apikeys.new().
Consumer keys can typically be obtained from the respective service's Web interface.
\subsection ods_authentication_oauth OAuth Authentication
Both registration and authentication through OAuth requires the user to log into the corresponding service (for example Twitter)
and authenticate ODS for login. This involves the client navigating to the login page of the service which will then perform a
redirect to the ODS client for further processing.
ODS implements this process through two functions. Clients can initiate the process through user.authenticate.authenticationUrl() which will take
a callback URL as parameter and will return the service's login page URL. The client will then have to open that page and let
the user login. This will result in a redirection to the callback URL which will have the result encoded in query parameters. The parameters
either describe a new session object, a confirmation request, or an error as described in \ref ods_authentication_url_workflow.
A confirmation request can be completed via user.authenticate.confirm().
*/
/**
\page ods_response_format Response format
The following Response format is used by the ODS.
\section ods_response_format_result_code ODS Error Result Codes
CRUD operations typically return an error/result code serialized as XML. Such an error code typically looks as follows:
\verbatim
<result>
<code>NNN</code>
<message>human readable explanation if applicable</message>
</result>
\endverbatim
It contains a numeric error code and a human-readable error message. On success this message is typically "Success".
Many ODS functions return the numerical id of the current resource as the code. Typical examples are functions that create
resource like calendar.event.create().
The ODS API is slowly moving towards using HTTP error codes in addition to the respones codes above. Many methods still
finish with a <em>200 OK</em> even in the error case. The individual method documentation reflects which methods have already
been updated to use HTTP error codes.
\section ods_response_format_search_result ODS Search Results
The search methods return results in RDF format according to FOAF, SIOC and SIOC types module ontology. See ODS RDF model.
*/
/**
\page ods_console ODS Console
ODS has a comprehensive HTTP API. To easy testing and development ODS provides a graphical console which can be used to initiate calls
to any of the API functions. The \em ODS \em Console can be installed on any system to access any ODS instance given that instance has
enabled the CORS support for cross-domain AJAX calls.
\section ods_console_try Try ODS Console
ODS Console is a pure client-side JS application which can be run from any location including a local folder or
<a href="http://web.ods.openlinksw.com/ods-console/">OpenLink's own test installation of ODS Console</a>. By default the console will
access the ODS installation on the same domain. However, if the host of the Console installation has been added as a client to the ODS
instance (admin.client.new()) it can be used to access the API of the ODS instance by simply setting the ODS host in the Console configuration:
\image html ods-console-cfg.png
The ODS API is always accessible at path \p ods/api/. This path should not be included in the configuration setting as ODS Console will
add it automatically.
\section ods_console_install Install ODS Console
ODS Console can also be run locally or on one's own Virtuoso instance. In fact since the Console is a simply JS application it can be
served from any web server, not restricted to Virtuoso.
\subsection ods_console_install_vad ODS Console VAD Package
The simplest way to install ODS-Console is to <a href="http://web.ods.openlinksw.com/~trueg/downloads/ods-console/">download the ods-console VAD package</a>
and install it via Virtuoso's Conductor. Log into the Condictor with dba privileges and navigate to the System Admin -> Packages page. From there select
the downloaded file in the section called "Upload package" and continue with the "Proceed" button. After the successful installation ODS Console will be
available at the Virtuoso instance under the path \p ods-console/.
\subsection ods_console_install_git Fork ODS Console on GitHub
ODS Console is developed as an open-source project on GitHub. From here it can easily be downloaded or forked:
<a href="http://github.com/opendataspaces/ods-console/">ODS Console on GitHub</a>
*/
|
